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Preface 


This manual provides users of the VAX/VMS operating system with detailed 
usage and reference information on the Run-Time Library routines. 

Run-Time Library routines can only be used in programs written in languages 
that produce native code for the VAX hardware. At present, these languages 
include VAX MACRO and the following compiled high-level languages: 


VAX Ada 
VAX BASIC 
VAX BLISS-32 
VAX C 
VAX COBOL 
VAX COBOL-74 
VAX CORAL 
VAX DIBOL 
VAX FORTRAN 
VAX PASCAL 
VAX PL/I 
VAX RPG 
VAX SCAN 


Interpreted languages which can also access Run-Time Library routines 
include VAX DSM and DATATRIEVE. 


Intended Audience 

This manual is intended for system and application programmers who want 
to call Run-Time Library routines. 


Structure of This Document 

This manual is organized into two parts as follows: 

• Part I provides guidelines on the use of Run-Time Library procedures. 

Section 1 introduces the Run-Time Library. It presents overviews 
of the categories of Run-Time Library procedures and explains the 
documentation format of the routine descriptions in Part II. 

Section 2 describes how to call Run-Time Library procedures. Special 
attention is given to passing arguments, selecting appropriate facilities, 
and the use of Run-Time Library procedures from MACRO and BLISS. 

For additional information about a particular high-level language and 
programming examples in that language, see that language's user's guide. 

Sections 3 through 6 guide new users in understanding how the Run-Time 
Library routines work and how to use them. Examples are provided 
throughout when appropriate. 

Sections 7, 8, 9, and 10 address condition handling, accessing system 
components, memory allocation, and image intitialization and termination. 
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• Part II provides detailed reference information on each Run-Time Library 
procedure. This information is described using the documentation format 
presented in Section 1.4. Procedure descriptions appear in alphabetical 
order by procedure name. 


Associated Documents 

The VAX Procedure Calling and Condition Handling Standard, which is 
documented in Section 2.5 of the Introduction to System Routines , contains 
useful information for anyone who wants to call Run-Time Library routines. 

VAX MACRO programmers will find additional information on calling 
Run-Time Library routines in the VAX MACRO Language Reference Manual 
and in the VAX MACRO User's Guide. 

High-level language programmers will find additional information on calling 
Run-Time Library routines in the language reference manual. Additional 
information may also be found in the language user's guide provided with 
your VAX language. 

The Guide to Using DCL and Command Procedures on VAX/VMS may also be 
useful. 

For a complete list and description of the manuals in the VAX/VMS 
document set, see the Introduction to the VAX/VMS Document Set. 


Conventions Used in This Document 


Convention Meaning 

[return | A symbol with a one- to six-character 

abbreviation indicates that you press a key 
on the terminal, for example, I return | . 

[ctrl/x| The phrase CTRL/x indicates that you 

must press the key labeled CTRL while you 
simultaneously press another key, for example, 
CTRL/C, CTRL/Y, CTRL/O. 

$ SHOW TIME Command examples show all output lines or 

05-JUN-1985 11:55:22 prompting characters that the system prints 

or displays in black letters. All user-entered 
commands are shown in red letters. 

$ TYPE MYFILE.DAT Vertical series of periods, or ellipsis, mean either 

that not all the data that the system would 
display in response to the particular command is 
shown or that not all the data a user would enter 
is shown. 

file-spec,... Horizontal ellipsis indicates that additional values, 

or information can be entered. 

[logical-name] Square brackets indicate that the enclosed item 

is optional. (Square brackets are not, however, 
optional in the syntax of a directory name in a 
file specification or in the syntax of a substring 
specification in an assignment statement.) 
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Convention 

Meaning 

quotation marks 
apostrophes 

The term quotation marks is used to refer 
to double quotation marks ("). The term 
apostrophe (') is used to refer to a single 
quotation mark. 


Other conventions used in this document are described in Section 1.4 of 
this manual, which is titled "Documentation Format for Run-Time Library 
Routines." 
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New and Changed Features 


DTK$, a new Run-Time Library Facility, is available in Version 4.4. For use 
with DIGITAL's DECtalk devices, it contains all the routines in the following 
list. 


New DTK$ Procedure 

Function 

DTK$ANSWER_PHONE 

DTK$DIAI_PHONE 

DTK$HANGUP_PHONE 

DTK$INITIALIZE 

DTK$LOAD_DICTIONARY 

DTKSREAD—KEYSTROKE 

DTK$READ_STRING 

Answers the phone 

Dials the phone 

Hangs up the phone 

Initializes the DECtalk device 

Loads a word into the DECtalk dictionary 

Reads a key entered on the keypad 

Reads a series of keys entered on the 
keypad 

DTK$RETURN_LAST_INDEX 

DTK$SET_INDEX 

DTK$SET_KEYPAD_MODE 

DTK$SET_LOGGING_MODE 

DTK$SET_MODE 

DTK$SET_SPEECH _MODE 

DTK$SET_TERMINA1_MODE 

DTK$SET_VOICE 

Returns the last index spoken 

Inserts an index 

Turns the phone keypad on and off 

Sets or resets logging mode 

Sets or resets the specified mode 

Starts or stops DECtalk's speech 

Sets or resets terminal mode 

Sets the voice characteristics of the 
DECtalk device 

DTK$SPEAK_FILE 

DTK$SPEAK_PHONEMIC_TEXT 

DTK$SPEAK_TEXT 

DTKSTERMINATE 

Speaks the text in the specified file 
Speaks the specified phonemic text 
Speaks the specified text 

Terminates the use of the DECtalk 
device 


There are several new procedures available in Versions 4.2 and 4.4. These 
procedures and their functions are as follows: 


New Procedure 

Function 

New LIBS Procedures 

LIB$CREATE_USER_VM_ZONE 

LIB$CREATE_VM_ZONE 

LIB$DELETE_VM_ZONE 

LIBSPAUSE 

LIB$RESET_VM_ZONE 

Creates a user-controlled storage area 

Creates a new zone 

Deletes a zone 

Suspends program execution 

Resets a previously created zone 
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New and Changed Features 


New MTH$ Procedures 
MTH$UMIN 

MTHSUMAX 

New SMG$ Procedures 

SMG$COPY_VIRTUAL—DISPLAY 

SMGSDISABLE-BROADCAST¬ 
TRAPPING 

SMG$GET_KEYBOARD— ' 
ATTRIBUTES 

SMG$GET_NUMERIC—DAT A 

SMGSGET—PASTING—INFO 

SMGSPUT—LINE—HIGH WIDE 

SMG$RE AD_KEYSTROKE 

SMG$RE AD_VERIFY 
SMGSREPAINT—LINE 

SMG$REPLACE_INPUT—LINE 

SMGSRETURN—INPUT—LINE 
SMG$SET_CURSOR—MODE 


Provides an unsigned version of 
MTHSJMINO 

Provides an unsigned version of 
MTHSJMAXO 

Creates a copy of a virtual display 

Disables the trapping of broadcast 
messages 

Retrieves information about a virtual 
keyboard 

Allows better performance when 
only retrieving numeric data from 
TERMTABLE.EXE 

Retrieves information about a virtual 
display 

Outputs double high/double wide lines 
to display 

Allows the caller to read one keystroke 
from the terminal 

Provides support for read verify QIO 

Allows the user to repaint one or more 
contiguous lines 

Replaces lines in the recall buffer with a 
specified string 

Returns a line from the recall buffer 
Turns the physical cursor on and off 


New arguments have been added to the following existing routines: 

• LIB$GET_VM 

• LIB$FREE_VM 

• SMG$CRE ATE -VIRTUAL -KEYBOARD 

• SMG$MOVE-VIRTUAL-DISPLAY 

• SMG$PASTE_VIRTUAL-DISPLAY 

• SMG$PUT_LINE 

• SMG$READ_COMPOSED—LINE 

• SMG$PUT_PASTEBOARD 

• SMG$READ_FROM—DISPLAY 

• SMG$ READ—KEYSTROKE 

• SMG$READ_STRING 

• SMG$READ_VERIFY 

• SMG$REPASTE-VIRTUAL-DISPLAY 

• SMG$SNAPSHOT 
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New and Changed Features 


The following procedures are now obsolete: 

• LIB$SYS_TRNLOG. The system service SYS$TRNLOG is obsolete 
and has been replaced by SYS$TRNLNM. Because LIB$SYS_TRNLOG 
was a jacket routine to the SYS$TRNLOG system service, this routine 
is also obsolete. Due to the expanded capabilities of most languages 
in calling Run-Time Library routines and system services, LIB$SYS_ 
TRNLOG will not be replaced. 

• SMG$PUT_WITH—SCROLL. The routine SMG$PUT_LINE now 
supports scrolling, therefore the SMG$PUT_WITH— SCROLL routine is 
obsolete. 

• SMG$ALLOW—ESCAPE. This routine was created solely for the 
purpose of translating old application programs that send escape 
sequences to SMG$, and is no longer supported. 

These routines remain in the documentation for this update but will be 
removed for the next major release of the documentation. 

Within the LIB$ facility, new algorithms have been implemented in 
LIB$GET_VM and LIB$FREE_VM. 

In the MTH$ facility, new algorithms have been implemented to improve 
the accuracy of the following hyperbolic routines to less than one least 
significant bit (LSB). 

• MTHSSINH, MTH$DSINH, and MTH$GSINH 

• MTH$COSH, MTH$DCOSH, and MTH$GCOSH 

• MTH$TANH, MTH$DTANH, and MTH$GTANH 

Within the SMG$ facility, several other enhancements have been made. 
These are as follows: 

• There is now an added check on validity of rendition arguments. 

• Display IDs of 0 have been disallowed. 

• Input routines now use Termtable, thus providing support for foreign 
terminals. 

• Input routines now support scrolling if a Display ID is given. 

• Output can no longer be written past the last row and column of the 
pasteboard. 

• SMG$INVALIDATE—DISPLAY now re-draws the borders as well as 
the text for an invalidated display. 

• SMG$PUT_VIRTUAL-DISPLAY-ENCODED has been enhanced to 
handle more than 40 triplets. 

• Proper line wrapping is now provided for double wide and double 
high/wide lines. 

• The check for AVO (advanced video) bit has been removed to allow 
reverse video and underlining when the AVO bit is not set. 

• Updated terminal definitions for new and missing capabilities have 
been added to TERMTABLE.EXE. 

• The following new capabilities have been added to SMGBLDTRM.EXE: 

BEGIN-AUTOPRINT-MODE 
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New and Changed Features 


BEGIN _AUTOREPEAT_MODE 
BEGIN _AUTOWRAP_MODE 
DEC-CRT-2 (Boolean) 

END—AUT OPRINT_MODE 
END_AUTOWRAP_MODE 
END_AUTOREPEAT__MODE 
ERASE _LINE _TO_CURSOR 
NEXT-LINE 
PRINT-SCREEN 
SET_CURSOR_OFF 
SET—CURSOR—ON 
SET-ORIGIN -ABSOLUTE 
SET-ORIGIN-RELATIVE 
SET_PRINTER_OUTPUT 
SET-SCREEN -OUTPUT 

• The capability for nonminimal updating is now supported. Non- 
minimal updating redraws only those lines affected by a change, 
beginning at the first changed character and proceeding to the end of 
the line. 

• Documentation has been added to Chapter 3 concerning user-written 
exit handlers for screen management routines. This documentation 
explains why pasteboards and virtual keyboards cannot be deleted 
from within a user-written exit handler. 

• Due to changes made to the Screen Management Facility, the following 
restriction now applies to the routines SMG$SET_BROADCAST- 
TRAPPING, SMG$ENABLE_UNSOLICITED—INPUT, and SMG$SET_ 
OUT—OF_BAND—ASTS. For AST routines written in a language 
which does not support optional parameters, all system parameters 
must be specified. This restriction is illustrated in the example for the 
SMG$DIS ABLE-BROADCAST-TRAPPING routine. 


XXX 
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Part I Using Run-Time Library Routines 

Part I of this book contains information about how to call and use 
the Run-Time Library routines. 
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Introduction 


The VAX Common Run-Time Procedure Library (or simply the Run-Time 
Library) contains two types of procedures: 

• General purpose procedures 

• Language support procedures 


The general purpose procedures are intended to be called explicitly from 
user written programs to perform common operations. The language support 
procedures are intended to be called implicitly by compiler-generated code. 
Although the Run-Time Library contains both the general purpose and the 
language support procedures, the term Run-Time Library procedures is used to 
reference only the general purpose procedures. 

Procedures in the Run-Time Library follow the VAX Procedure Calling 
and Condition Handling Standard in the Introduction to VAX/VMS System 
Routines , and the VAX/VMS Modular Programming Standard in the Guide to 
Creating Modular Procedures on VAX/VMS. Because these procedures are part 
of the VAX/VMS common run-time environment, they may be called from 
any VAX language. This common run-time environment lets your program 
contain procedures written in different languages, thus increasing program 
flexibility. 


In this manual, a procedure (or routine) is defined as a set of related 
instructions that performs a particular task. It is an executable program unit 
and can be a main program, subroutine, or function. A procedure has an 
entry point and an argument list. It may also return a function value or 
completion status to the program that calls it. 



1.1 



Features of the Run-Time Library 

The Run-Time Library provides the following features and capabilities: 

• Run-Time Library procedures perform a wide range of general utility 
operations. You can call a Run-Time Library procedure from any VAX 
language instead of writing code to perform the operation. 

Procedures in the Run-Time Library are part of the VAX Common 
Run-Time environment; therefore, they can be called from any VAX 
language. Because they follow the VAX/VMS Modular Programming 
Standard, Run-Time Library procedures can be easily incorporated into a 
program. 

• The resource allocating procedures of the Run-Time Library provide a 
central repository for process resources such as virtual memory and event 
flags. 

• Because many of the procedures are shared, they take up less space in 
memory. 

• When new versions of the Run-Time Library are installed, you do not 
need to revise your calling program, and generally do not need to relink. 
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• All Run-Time Library procedures (that is, the general purpose procedures) 
are fully reentrant unless the description of the facility or the procedure 
specifies otherwise. 

The term reentrant means that the procedure executes correctly regardless 
of how many threads of execution are executing at the same time. 
Currently, reentrancy is supported only when those multiple threads 
are executing on the same processor. Among the language support 
procedures, FORTRAN (FOR$), BASIC (BASS), and PASCAL (PASS) 
procedures are AST-reentrant only. The term AST-reentrant means that 
the procedure may be interrupted and reentered from itself or an AST 
level thread of execution only. In particular, an AST-reentrant procedure 
may not execute properly if more than one non-AST level thread of 
execution is executing the procedure at once. For further information 
about reentracy and AST reentrancy, see the Guide to Creating Modular 
Procedures on VAX/VMS. 

Because the Run-Time Library procedures are reentrant (unless otherwise 
noted), they can be called from multiple threads of execution. For 
example, a procedure may be called from both an AST level thread and a 
non-AST level thread of an image, as well as from the multiple tasks of 
an Ada program. 


1.2 Linking with the Run-Time Library 

Procedures in the Run-Time Library execute entirely in the mode of the caller 
and are intended to be called in user mode. This section explains how to link 
your program and the Run-Time Library together into a single executable 
unit. 

When you link your program, the VAX/VMS Linker creates an executable 
image. If your program includes explicit or implicit calls to the Run-Time 
Library, the linker automatically searches the following system libraries for 
the named procedures: 

• The system default shareable image library, IMAGELIB.OLB 

The linker first searches IMAGELIB.OLB to resolve undefined symbols. 
The most frequently used portions of the Run-Time Library are contained 
in this set of shareable images. When you link your program, your 
program is linked by default with the shareable images in this library to 
form an executable image. 

• The system default object module library, STARLET.OLB 

A portion of the Run-Time Library is contained as object modules 
in STARLET.OLB. If the linker does not find the procedure in 
IMAGELIB.OLB, it copies the procedure from STARLET.OLB into your 
program's executable image. 

When your program calls a procedure that is part of a shareable image, the 
linker does not copy the procedure into your program's executable image. 

Using shareable images offers the following advantages: 

• Many programs can use the single copy, so each program takes up less 
space in physical memory and less disk storage. 
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• More than one program can use a shareable image simultaneously, thus 
saving memory space. 

• When new versions of the Run-Time Library are installed, you do not 
need to relink the programs that call the shareable Run-Time Library. 


1.3 Organization of the Run-Time Library 

The Run-Time Library contains several facilities. The facilities represent 
groups of procedures that perform related operations. The Run-Time Library 
procedures are grouped into the following facilities: 

LIBS General purpose procedures 

MTH$ Mathematics procedures 

OTS$ Language-independent support procedures 

SMG$ Screen management procedures 

STR$ String manipulation procedures 

The characteristics of the facility's procedures are determined by the kind of 
operations they perform. Therefore, the facilities differ in the conventions 
they use for handling errors and receiving arguments. For further details, see 
Section 2. 

Figure 1-1 summarizes the organization of these Run-Time Library facilities. 

Figure 1-1 Organization of the VAX Run-Time Library 
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The language support procedures of the Run-Time Library are also divided 
into separate shareable images. These shareable images, as well as the 
Run-Time Library procedures shareable images, reside in the shareable image 
library SYS$LIBRARY:IMAGELIB.OLB. 
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1.3.1 Run-Time Library Procedures 

In most cases, user programs call the Run-Time Library procedures using 
explicit procedure or function calls. These calls are made according to the 
syntax of the source language. Section 2 shows how to call a Run-Time 
Library procedure explicitly. 

The Run-Time Library procedures include the following types of procedures: 

• General utility procedures 

These include procedures for getting a record from a device, performing 
string manipulation, converting data types for input and output, and 
obtaining the system date or time. Frequently used string handling 
procedures have both JSB and CALL entry points. 

• Mathematics procedures 

Mathematics procedures perform common arithmetic, algebraic, and 
trigonometric functions. Frequently used mathematics procedures have 
both JSB and CALL entry points. 

• Resource allocation procedures 

Resource allocation procedures allocate and deallocate virtual memory, 
VAX/VMS local event flag numbers, BASIC/FORTRAN logical unit 
numbers, and dynamic strings. 

• Screen management procedures 

Screen management procedures perform terminal-independent screen 
management functions. These procedures assist you in designing, 
composing, and keeping track of complex images on a video screen. 

• Signaling and condition handling procedures 

These procedures perform operations involved with handling exception 
conditions, such as signaling exceptions, establishing condition handlers, 
and enabling the detection of hardware exceptions. 

• Syntax analysis procedures 

Syntax analysis procedures analyze the syntax of strings. The library 
includes two of these: a table-driven parser called LIB$TPARSE and a 
procedure called LIB$LOOKUP_KEY that recognizes keywords. 

• Cross-reference procedures 

The cross-reference procedures accept cross-reference data, summarize 
it, and format it for output. Your program accesses the cross-reference 
procedures through a set of control blocks and format definition tables. 

• Language-independent support procedures 

Language-independent support procedures are used by compiler-generated 
code to do specific tasks such as data type conversions. 
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1.4 


Documentation Format for Run-Time Library Routines 

Each Run-Time Library routine is documented using a structured format 
called the routine template. This section discusses the main headings in the 
routine template, the information that is presented under each heading, and 
the format used to present the information. 

The purpose of this section, therefore, is to explain where to find information 
and how to read it correctly not how to use it. For information on using 
Run-Time Library routines, see Section 2. 

Some main headings in the routine template contain information that requires 
no further explanation beyond what is given in Table 1-1. However, the 
following main headings contain information that does require additional 
discussion, and this discussion takes place in the remaining subsections of 
this section. 

• Format heading 

• Returns heading 

• Arguments heading 

• Condition values returned heading 


Table 1-1 Main Headings in the Routine Template 

Main Heading Description 


Routine name 


Routine overview 


Format 


Returns 


Arguments 


Description 


Required. The routine entry point name appears at the 
top of the first page. It is usually, though not always, 
followed by the English text name of the routine. 

Required. The routine overview appears directly below 
the routine name; the overview explains, usually in one 
or two sentences, what the routine does. 

Required. The format heading follows the routine 
overview. The format gives the routine entry point 
name and the routine argument list. 

Required. The returns heading follows the routine 
format. It explains what information is returned by the 
routine. 

Required. The arguments heading follows the returns 
heading. Detailed information about each argument 
is provided under the arguments heading. If a routine 
takes no arguments, the word "None" appears. 

Optional. The description heading follows the 
arguments heading. The description section contains 
information about specific actions taken by the 
routine: interaction between routine arguments, if 
any; operation of the routine within the context of 
VAX/VMS; user privileges needed to call the routine, if 
any; system resources used by the routine; and user 
quotas that may affect the operation of the routine. 
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Table 1-1 (Cont.) Main Headings in the Routine Template 


Main Heading 

Description 


Note that any restrictions on the use of the routine 
are always discussed first in the description 
section; for example, any required user privileges 
or necessary system resources are explained first. 


For some simple routines, a description section is not 
necessary because the routine overview carries the 
needed information. 

Condition values 
returned 

Required. The condition values returned section 
appears following the description section. It lists the 
condition values (typically status or completion codes) 
that are returned by the routine. 

Example 

Optional. The examples heading appears following 
the condition values returned heading. The example 
section contains one or more programming example(s) 
to illustrate use of the routine. Following the example, a 
text explanation of the example is given. 


All examples have been tested and should run when 
compiled (or assembled) and linked. 


1.4.1 Format Heading 

Under the format heading, the following three types of information can be 
present. 

• Procedure call format 

• Jump to Subroutine (JSB) format 

• Explanatory text 

All Run-Time Library routines have a procedure call format, but not all 
Run-Time Library routines have JSB formats; in fact, most do not. If a routine 
has a JSB format, it always appears after the routine's procedure call format. 

Use of the procedure call format results in a routine call conforming to the 
procedure call mechanism described in the VAX Procedure Calling and 
Condition Handling Standard in Introduction to VAX/VMS System Routines; 
for example, an entry mask is created, registers are saved, and so on. 

Use of the JSB call format results in activation of the routine code directly, 
without the overhead of constructing the entry mask, saving registers, and so 
on. The JSB call format can be used only by VAX MACRO and VAX BLISS 
programmers. 

Explanatory text may appear following one or both of the above formats. 

This text is present only when needed to clarify the format(s). 

A procedure call format appears under the format heading as follows: 

ENTRY-POINT-NAME argl ,arg2 ,[arg3] .nullarg [,arg4] [,arg5] 
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The preceding format exemplifies the use of the following syntax rules. 


Element 

Syntax Rule 

Entry point names 

Entry point names are always shown in uppercase 
characters. 

Argument names 

Argument names are always shown in lowercase 
characters. 

Spaces 

One or more spaces are used between the entry 
point name and the first argument, and between 
each argument. 

Brackets ([ ]) 

Brackets surround optional arguments; arg3, arg4, 
and arg5 (in the example above) are optional 
arguments because they are surrounded by 
brackets. 

Commas 

Between arguments, the comma always follows 
the space. If the argument is optional, the 
comma may appear inside the brackets or 
outside the brackets, depending on the position 
of the argument in the list and on whether 
surrounding arguments are optional or required. 

For example, arg3 in the above format is an 
optional argument; but because there are 
other required arguments that follow arg3 
in the list, the comma itself is not optional 
(since it marks the place of arg3); therefore, 
the comma is not inside the brackets. 

Null arguments 

The arguments arg4 and arg5 are optional. 

Because there are no required arguments that 
follow arg4 and arg5 in the list, the commas in 
front of arg4 and arg5 are themselves optional; 
that is, the commas would not be specified in 
the call if arg4 and arg5 were not specified. 
Therefore, the commas in front of arg4 and arg5 
are inside the brackets. Note however that if arg5 
is specified, the comma in front of arg4 is required 
whether or not arg4 is specified. 

A null argument is a place-holding argument. It 
is used for either of the following two reasons: 

(1 ) to hold a place in the argument list for an 
argument that has not yet been implemented 
by DIGITAL but which may be at some future 
time or (2) to mark the position of an argument 
that was used in earlier versions of the routine 
but which is not used in the latest version 
(upward compatibility is thereby ensured because 
arguments that follow the null argument in the 
argument list keep their original positions). A 
null argument is always given the name "nullarg". 
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Element 


Syntax Rule 


In the argument list constructed when a procedure 
is called, both null arguments and omitted 
optional arguments are represented by longword 
argument list entries containing the value 0. The 
programming language syntax required to produce 
argument list entries containing 0 differs from 
language to language, so you should refer to your 
language user's guide for language-specific syntax. 

However, in general, the following rule applies to 
high-level languages: To mark a null argument or 
to omit an optional argument in the call, specify 
a comma (,) for each null argument or omitted 
optional argument. 


1.4.2 Returns Heading 

Under the returns heading appears a description of what information, if any, 
is returned by the routine to the caller. A routine can return information 
to the caller in various ways. The subsections that follow discuss each 
possibility and then describe how this returned information is presented 
under the returns heading. 


1.4.2.1 Condition Values in RO 

Most routines return a condition value in register RO. This condition value 
contains various kinds of information, but most importantly for the caller, 
it describes (in bits 0 through 3) the completion status of the operation. 
Programmers test the condition value to determine if the routine completed 
successfully. 

For the purposes of high-level language programmers, the fact that status 
information is returned by means of a condition value and that it is returned 
in a VAX register is of little importance because the high-level language 
programmer receives this status information in the return (or status) variable 
he or she uses when making the call. The run-time environment established 
for the high-level language program allows the status information in RO to be 
moved automatically to the user's return variable. 

Nevertheless, if a routine returns a condition value in RO, the returns heading 
in the documentation will contain the following information: 

VMS Usage: cond.value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

The "VMS Usage" heading specifies how the data type is used by the VMS 
operating system. 

The "type" heading specifies the data type of the information returned. 

Since the data type of a condition value is an unsigned longword, the "type" 
heading shows "longword (unsigned)". 

The "access" heading specifies the way in which the called routine accesses 
the object. Since the called routine is returning the condition value, it is 
writing into this longword; so the "access" heading shows "write only". 
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The "mechanism" heading specifies the passing mechanism used by the called 
routine in returning the condition value. Since the called routine is writing 
the condition value directly into RO, the mechanism heading shows "by 
value". (If the called routine had written the address of the condition value 
into RO, the passing mechanism would have been "by reference".) 

Note that if a routine returns a condition value in RO, another main heading 
in the routine template (Condition Values Returned) describes the possible 
condition values that the routine can return. 


1.4.2.2 Data in Registers RO Through R11 

Some routines return actual data in the VAX registers. The number of 
registers needed to contain the data depends on the length (or data type) 
of the information being returned. For example, a Run-Time Library 
mathematics routine that is returning the cosine of an angle as a G—floating 
number would use registers RO and R1 because the length of a G_floating 
number is two longwords. 

If a routine returns actual data in one or more of the registers RO through 
Rll, the returns heading in the documentation of that routine will contain the 
following information: 

vms Usage: yyyyyyyy 

type: xxxxxxxx 

access: write only 

mechanism: by value 

The symbol "yyyyyyyy" indicates the VMS Usage of the information. In this 
particular case, the VMS Usage would be floating-point. 

The symbol "xxxxxxxx" above indicates the data type of the information being 
returned. For example, for the mathematics routine discussed above, the data 
type would be G_floating. 

In addition, under the returns heading, following the information about the 
type, access, and mechanism, some text may be provided. This text explains 
other relevant information about what the routine is returning. 

For example, since the routine is returning actual data in the VAX registers, 
the registers cannot be used to convey completion status information. All 
routines that return actual data in VAX registers must signal the condition 
value, which contains the completion status. Thus, the text under the returns 
heading will point out that the routine signals its completion status. 


1.4.2.3 Condition Values Signaled 

Though most routines return condition values in RO, some routines choose to 
signal their condition values using the VAX Signaling Mechanism. Routines 
can signal their completion status whether or not they are returning actual 
data in the VAX registers. But all routines that return actual data in the VAX 
registers must signal their completion status if they are to return this status 
information at all. 

If a routine signals its completion status, text under the returns heading 
explains this fact. 

Note that if a routine signals its condition value, another main heading in the 
routine template (Condition Values Signaled) describes the possible condition 
values that the routine can signal. 

Run-Time Library routines provided by DIGITAL never signal condition 
values indicating success. Only error condition values are signaled. 


1-9 





Introduction 

Documentation Format for Run-Time Library Routines 


1.4.3 Arguments Heading 

Under the arguments heading appears detailed information about each 
argument listed in the call format. Arguments are described in the order in 
which they appear in the call format. If the routine has no arguments, the 
term "none" appears. 

The following format is used to describe each argument. 

argument-name 

VMS Usage: VMS-Usage-type 

type: argument-data-type 

access: argument-access 

mechanism: argument-passing-mechanism 

One paragraph of structured, text, followed by other 
paragraphs of text, as needed. 


1.4.3.1 VMS Usage Entry 

The VMS usage entry indicates the abstract data structure of the argument. 

Table 1-2 contains a list of the VMS data structures. 

Table 1-2 VMS Data Structures 

Data Structure Definition 

access_bit_names Homogeneous array of 32 quadword 

descriptors; each descriptor defines the name 
of one of the 32 bits in an access mask. 

The first descriptor names bit 0, the second 
descriptor names bit 1 and so on. 

access_mode Unsigned byte denoting a hardware access 

mode. This unsigned byte can take four 
values: 0 specifies kernel mode; 1, executive 
mode; 2, supervisor mode; and 3, user mode. 

address Unsigned longword denoting the virtual 

memory address of either data or code, but 
not of a procedure entry mask (which is of type 
“procedure"). 

address_range Unsigned quadword denoting a range of virtual 

addresses, which identify an area of memory. 
The first longword specifies the beginning 
address in the range; the second longword 
specifies the ending address in the range. 

arg_list Procedure argument list consisting 

of one or more longwords. The first 
longword contains an unsigned integer 
count of the number of successive, 
contiguous longwords, each of which is 
an argument to be passed to a procedure 
by means of a VAX CALL instruction. 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


The argument list has the following format: 



ast_procedure 

boolean 

byte_signed 

byte_unsigned 

channel 

char_string 


complex_number 


Unsigned longword integer denoting the entry 
mask to a procedure to be called at AST level. 
(Procedures that are not to be called at AST 
level are of type "procedure".) 

Unsigned longword denoting a boolean truth 
value flag. This longword may have only two 
values: 1 (true) and 0 (false). 

This VMS data type is the same as the data 
type "byte integer (signed)" in Table 1-3 

This VMS data type is the same as the data 
type "byte integer (unsigned)" in Table 1-3. 

Unsigned word integer that is an index to an 
I/O channel. 

String of from 0 to 65,535 8-bit characters. 
This VMS data type is the same as the data 
type "character string" in Table 1-3. The 
following diagram pictures the character string 
"XYZ". 

7 0 

: A 

: A + 1 
: A + 2 


“X” 


“Y” 


“Z” 
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One of the VAX standard complex floating¬ 
point data types. The three complex floating¬ 
point numbers are: F_floating complex, 
D_floating complex, and G_floating complex. 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


An F_floating complex number (r,i) is 
comprised of two F_floating point numbers. 
The first F_floating point number is the real 
part (r) of the complex number; the second 
F_floating point number is the imaginary part 
(i). The structure of an F_floating complex 
number is as follows: 
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A D_floating complex number (r,i) is comprised 
of two D_floating point numbers. The first 
D_floating point number is the real part (r) of 
the complex number; the second D_floating 
point number is the imaginary part (i). The 
structure of a D_floating complex number is as 
follows: 


15 14 76 0 


REAL 

PART 


IMAGINARY 

PART 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


: A 

: A+2 
: A+4 
: A+6 
: A8 
: A+10 
: A+12 
: A+14 


ZK-4201-85 


1-12 



























Introduction 

Documentation Format for Run-Time Library Routines 


Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


A G_floating complex number (r,i) is comprised 
of two G_floating point numbers. The first 
G_floating point number is the real part (r) of 
the complex number; the second G_floating 
point number is the imaginary part (i). The 
structure of a G_floating complex number is as 
follows: 


REAL 

PART 


IMAGINARY 

PART 


15 14 43 0 


! 

S 

EXPONENT 

FRACTION 

FRACTION 

FRACTION 

FRACTION 

S 

EXPONENT 

FRACTION 

FRACTION 

FRACTION 

FRACTION 


: A 

: A + 2 
: A+4 
: A+6 
: A8 
: A + 10 
: A + 12 
: A + 14 
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cond_value Unsigned longword integer denoting a 

condition value (that is, a return status or 
system condition code), which is typically 
returned by a procedure in RO. The structure 
of a condition value is as follows: 



facility number 


message number 


ZK-1795-84 

context Unsigned longword that is used by a called 

procedure to maintain position over an iterative 
sequence of calls. It is usually initialized by the 
caller, but thereafter manipulated by the called 
procedure. 
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Table 1-2 (Cont.) VMS Data Structures 


Data Structure 


Definition 


date_time 


device_name 


ef_cluster_name 


ef_number 


exit_handler_block 


31 


64-bit unsigned, binary integer denoting a 
date and time as the number of elapsed 
100-nanosecond units since 00:00 o'clock, 
November 17, 1858. This VMS data type is 
the same as the data type "absolute date and 
time" in Table 1-3. 

Character string denoting the 1- to 9-character 
name of a device. It can be a logical name, 
but if it is, it must translate to a valid device 
name. If the device name contains a colon 
(:), the colon and the characters past it are 
ignored. When an underscore (_) precedes 
device name string, it indicates that the string 
is a physical device name. 

Character string denoting the 1- to 15- 
character name of an event flag cluster. It 
can be a logical name, but if it is, it must 
translate to a valid event flag cluster name. For 
more information on how the system translates 
logical names to global section names see the 
"Event Flag Services" section of the VAX/VMS 
System Services Reference Manual. 

Unsigned longword integer denoting the 
number of an event flag. Local event flags 
numbered 32 to 63 are available to your 
programs. 

Variable-length structure denoting an exit 
handler control block. This control block, 
which describes the exit handler, is depicted in 
the following diagram. 


forward link (used by VMS only) 


exit handler address 


these 3 bytes must be 0 

arg. count 

Address of condition value (written by VMS) 



additional arguments for the 
exit handler; these are optional; 
one argument per longword 


ZK-1714-84 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 

fab Structure denoting an RMS file access block. 

A complete description of this structure is 
contained in the VAX Record Management 
Services Reference Manual. 

file_protection Unsigned word that is a 16-bit mask that 

specifies file protection. The mask contains 
four 4-bit fields, each of which specifies 
the protection to be applied to file access 
attempts by one of the four categories of 
user: from the rightmost field to the leftmost 
field, (1) system users, (2) the file owner, 

(3) users in the same UIC group as the 
owner, and (4) all other users (the world). 

Each field specifies, from the rightmost bit 
to the leftmost bit: (1) delete access, (2) 
execute access, (3) write access, (4) read 
access. Set bits indicate that access is denied. 

The following diagram depicts the 16-bit 
file-protection mask. 


WORLD 

GROUP 

OWNER 

SYSTEM 

D 

E 

W 

R 

D 

E 

w 

R 

D 

E 

W 

R 

D 

E 

W 

R 

15 

14 

13 

12 

11 

10 

9 

8 

7 

6 

5 

4 

3 

2 

1 

0 
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floating_point One of the VAX standard floating-point 

data types. These types are F_floating, 
D_floating, G_floating, and H_floating. 

The structure of an F_floating number is as 
follows: 

1514 76 0 

: A 

: A + 2 

31 16 

ZK-4197-85 


S 

EXPONENT 

FRACTION 

FRACTION 


1-15 

























Introduction 

Documentation Format for Run-Time Library Routines 


Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


The structure of a D_floating number is as 
follows: 


15 14 76 0 

: A 

: A + 2 
: A+4 
: A+6 


ZK-4198-85 

The structure of a G_floating number is as 
follows: 


S EXPONENT FRACTION 


FRACTION 


FRACTION 


FRACTION 


63 


48 


15 14 43 0 

: A 

: A + 2 
: A+4 
: A+6 

63 48 

ZK-4199-85 

The structure of an H_floating number is as 
follows: 


: A 

: A + 2 
: A+4 
: A+6 
: A + 8 
: A+10 
: A+12 
: A+14 

127 113 

ZK-4196-85 


15 14 


EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


FRACTION 


EXPONENT 


FRACTION 


FRACTION 


FRACTION 


FRACTION 
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Table 1-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 

function_code 

Unsigned longword specifying the exact 
operations a procedure is to perform. This 
longword has two word-length fields: the 
first field is a number specifying the major 
operation; the second field is a mask or bit 
vector specifying various suboperations within 
the major operation. 

io_status_block 

Quadword structure containing information 
returned by a procedure that completes 
asynchronously. The inforamtion returned varies 
depending on the procedure. The following 
figure illustrates the format of the information 
written in the IOSB. 

31 

16 

15 0 

count 

condition value 

device-dependent information 


ZK-856-82 


The first word contains a condition value 
indicating the success or failure of the 
operation. The condition values used 
are the same as for all returns from 
system services; for example, SS$_ 

NORMAL indicates successful completion. 

The second word contains the number 
of bytes actually transferred in the I/O 
operation. Note that for some devices this 
word contains only the low-order word of the 
count. For information on specific devices, 
see the VAX/VMS I/O Reference Volume. 

The second longword contains 
device-dependent return information. 

To ensure successful I/O completion and the 
integrity of data transfers, the IOSB should be 
checked following I/O requests, particularly for 
device-dependent I/O functions. For complete 
details on how to use the I/O status block, see 
the VAX/VMS I/O Reference Volume. 
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Table 1-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 

item_list_2 

Structure that consists of one or more item 
descriptors and that is terminated by a 
longword containing 0. Each item descriptor 
is a 2-longword structure that contains three 
fields. The following diagram depicts a single 
item descriptor: 

31 

15 0 

item code 

component length 

component address 


ZK-1709-84 


The first field is a word in which the service 
writes the length (in characters) of the 
requested component. If the service does not 
locate the component, it returns the value 0 in 
this field and in the component address field. 

The second field contains a user- 
supplied, word-length symbolic code 
that specifies the component desired. 

The item codes are defined by the 
macros that are specific to the service. 


The third field is a longword in which the 
service writes the starting address of the 
component. This address is within the input 
string itself. 

item_list_3 Structure that consists of one or more item 

descriptors and that is terminated by a 
longword containing 0. Each item descriptor 
is a 3-longword structure that contains four 
fields. The following diagram depicts the 
format of a single item descriptor. 


31 


15 


0 


item code 


buffer length 


buffer address 


return length address 


ZK-1705-84 


1-18 












Introduction 

Documentation Format for Run-Time Library Routines 


Table 1-2 (Cont.) 

VMS Data Structures 

Data Structure 

Definition 

item_quota_list 

The first field is a word containing a user- 
supplied integer specifying the length (in 
bytes) of the buffer in which the service 
writes the information. The length of the 
buffer needed depends upon the item code 
specified in the item code field of the item 
descriptor. If the value of buffer length is 
too small, the service truncates the data. 

The second field is a word containing a 
user-supplied symbolic code specifying 
the item of information that the service 
is to return. These codes are defined by 
macros that are specific to the service. 

The third field is a longword containing 
the user-supplied address of the buffer in 
which the service writes the information. 

The fourth field is a longword containing the 
user-supplied address of a word in which 
the service writes the length in bytes of the 
information it actually returned. 

Structure that consists of one or more quota 
descriptors and that is terminated by a byte 
containing a value defined by the symbolic 
name PQL$_LISTEND. Each quota descriptor 
consists of a 1-byte quota name followed by 
an unsigned longword containing the value for 
that quota. 

lock_id 

Unsigned longword integer denoting a lock 
identifier. This lock identifier is assigned by the 
lock manager facility to a lock when the lock is 
granted. 

lock_status_block 

Structure into which the lock manager 
facility writes status information about a 
lock. A lock status block always contains at 
least two longwords: the first word of the 
first longword contains a condition value; 
the second word of the first longword 
is reserved to DIGITAL; and the second 
longword contains the lock identifier. 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


The lock status block receives the final 
condition value and the lock identification, and 
optionally contains a lock value block. When 
a request is queued, the lock identification is 
stored in the lock status block even if the lock 
has not been granted. This allows a procedure 
to dequeue locks that have not been granted. 

The condition value is placed in the lock 
status block only when the lock is granted 
(or when errors occur in granting the lock). 

The following diagram depicts a lock status 
block that includes the optional 16-byte lock 
value block. 


reserved 

condition value 

lock identification 


16 byte lock value block 
only used when LCK$M_VALBLK is set 


ZK-376-81 


lock_value_block 


logical_name 


longword—signed 
longword—unsigned 
mask_byte 


16-byte block that the lock manager facility 
includes in a lock status block if the user 
requests it. The contents of the lock value 
block are user defined and are not interpreted 
by the lock manager facility. 

Character string of from 1 to 255 characters 
that identifies a logical name or equivalence 
name to be manipulated by VMS logical name 
system services. Logical names that denote 
specific VMS objects have their own VMS 
types: for example, a logical name identifying a 
device has the VMS type "device-name". 

This VMS data type is the same as the data 
type "longword integer (signed)" in Table 1-3. 

This VMS data type is the same as the data 
type "longword (unsigned)" in Table 1-3. 

Unsigned byte wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of "flags" or as a "bitmask". 
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Table 1—2 (Cont.) VMS Data Structures 

Data Structure Definition 


mask_longword 


mask_quadword 


mask_word 


null_arg 


octaword_signed 

octaword_unsigned 

page_protection 


Unsigned longword wherein each bit is 
interpreted by the called procedure. A mask 
is also referred to as a set of "flags" or as a 
"bitmask". 

Unsigned quadword wherein each bit is 
interpreted by the called procedure. A mask 
is also referred to as a set of "flags" or as a 
"bitmask". 

Unsigned word wherein each bit is interpreted 
by the called procedure. A mask is also 
referred to as a set of "flags" or as a "bitmask". 

Unsigned longword denoting a "null argument." 
A "null argument" is an argument whose only 
purpose is to "hold a place" in the argument 
list. 

This VMS data type is the same as the data 
type "octaword integer (signed)" in Table 1-3. 

This VMS data type is the same as the data 
type "octaword (unsigned)" in Table 1-3. 

Unsigned longword specifying page 
protection to be applied by the VAX 
hardware. Protection values are specified 
using bits 0 to 3; bits 4 to 31 are ignored. 


The $PRTDEF macro defines the following 
symbolic names for the protection codes: 


Symbol 

Description 

PRT$C_NA 

No access 

PRT$C_KR 

Kernel read only 

PRTSC—KW 

Kernel write 

PRTSC—ER 

Executive read only 

PRT$C_EW 

Executive write 

PRT$C_SR 

Supervisor read only 

PRT$C_SW 

Supervisor write 

PRT$C_UR 

User read only 

PRT$C_UW 

User write 

PRT$C_ERKW 

Executive read; kernel write 

PRT$C_SRKW 

Supervisor read; kernel 
write 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


PRT$C_SREW 

PRT$C_URKW 

PRT$C_UREW 

PRT$C_URSW 


Supervisor read; executive 
write 

User read; kernel write 
User read; executive write 
User read; supervisor write 


If the protection is specified as 0, the 
protection defaults to kernel read-only. 

procedure Unsigned longword denoting the entry mask 

to a procedure that is not to be called at AST 
level. (Arguments specifying procedures to 
be called at AST level have the VMS type 
"ast_procedure".) 

process-id Unsigned longword integer denoting a process 

identifier (PID). This process identifier is 
assigned by VMS to a process when the 
process is created. 

process_name Character string, containing 1 to 15 characters, 

that specifies the name of a process. 

quadword—signed This VMS data type is the same as the data 

type "quadword integer (signed)" Table 1-3. 

quadword_unsigned This VMS data type is the same as the data 

type "quadword (unsigned)" in Table 1-3. 

rights—holder Unsigned quadword specifying a user's access 

rights to a system object. This quadword 
consists of two fields: the first is an unsigned 
longword identifier (VMS type "rights_id") 
and the second is a longword bitmask 
wherein each bit specifies an access right. 

Once the identifier record exists in the rights 
database, you define the holder(s) of that 
identifier with the $ADD_HOLDER system 
service. You pass the binary identifier value 
with the id argument; you specify the holder 
with the holder argument, which is the address 
of a quadword data structure with the following 
format. 


UIC Identifier of Holder 


0 


ZK-1903-84 
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Table 1-2 (Cont.) 


VMS Data Structures 


Data Structure 


Definition 


One holder record exists in the rights database 
for each holder of each identifier. The holder 
record associates the holder with the identifier, 
specifies the attributes of the holder, and 
identifies the UIC identifier of the holder. The 
format of a holder record is: 


IDENTIFIER VALUE 


ATTRIBUTES 


UIC IDENTIFIER OF HOLDER 


(RESERVED) 


ZK-1907-84 



The rights database is an indexed file with 
three keys. The primary key is the identifier 
value, the secondary key is the holder id, and 
the third key is the identifier name. Through 
the use of the secondary key of the holder id, 
all the rights held by a process can be retrieved 
quickly when LOGINOUT creates the process 
rights list. 

rights_id Unsigned longword denoting a rights identifier, 

which identifies an interest group in the 
context of the VMS security environment. 

This rights environment may consist of all or 
part of a user's User Identification Code (UIC). 

The basic component of the VAX/VMS 
protection scheme is an identifier. This 
32-bit binary value represents various 
types of agents using the system. The 
types of agents represented include 
individual users, groups of users, and 
environments in which a process is operating. 

Identifiers have two formats in the rights 
database: UIC format and ID format. The high 
order bits of the identifier value specify the 
format of the identifier. Two high order zero 
bits identify a UIC format identifier; bit 31, 
set to one, identifies an ID format identifier. 
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Table 1-2 (Cont.) VMS Data Structures 

Data Structure Definition 


Each UIC identifier is unique and represents 
a system user. The UIC identifier contains 
the two high order bits that designate format, 
a member field, and a group field. Member 
numbers range from 0 to 65,534; group 
numbers range from 1 to 16,382. 


31 


0 


00 


group 


member 


UIC Format 


ZK-1905-84 

Bit 31, set to one, specifies ID format. Bits 
30 through 28 are reserved by DIGITAL. The 
remaining bits specify the identifier value. 


31 


0 


1000 


identifier 


ID Format 


ZK-1906-84 


To the system, an identifier is a binary 
value; however, to make identifiers easy 
to use, the system translates the binary 
identifier value into an identifier name. 

The binary value and the identifier name 
are associated in the rights database. 

An identifier name consists of 1-31 
alphanumeric characters and contains at least 
one nonnumeric character. An identifier name 
cannot consist entirely of numeric characters. 

It can include the characters A through Z, 
dollar signs ($) and underscores (_), as well 
as the numbers 0 through 9. Any lowercase 
characters are automatically converted to 
uppercase. 

rab Structure denoting an RMS record access 

block. A complete description of this structure 
is contained in the VAX Record Management 
Services Reference Manual. 

section_id Unsigned quadword denoting a global section 

identifier. This identifier specifies the version 
of a global section and the criteria to be used 
in matching that global section. 
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Table 1-2 (Cont.) VMS Data Structures 


Data Structure 

Definition 

section_name 

Character string denoting 1 to 43-character 
global section name. This character string 
can be a logical name, but it must translate 
to a valid global section name. For more 
information on how the system translates 
logical names to global section names see 
the “Memory Management" section of the 
VAX/VMS System Services Reference Manual. 

system_access_id 

Unsigned quadword that denotes a system 
identification value that is to be associated with 
a rights database. 

time_name 

Character string specifying a time value in VMS 
format. 

uic 

Unsigned longword denoting a User 
Identification Code (UIC). 

user_arg 

Unsigned longword denoting a user-defined 
argument. This longword is passed to a 
procedure as an argument, but the contents of 
the longword are defined and interpreted by 
the user. 

varying_arg 

Unsigned longword denoting a variable 
argument. A variable argument can have 
variable types, depending on specifications 
made for other arguments in the call. 

vector_byte_signed 

A homogeneous array whose elements are all 
signed bytes. 

vector_byte_unsigned 

A homogeneous array whose elements are all 
unsigned bytes. 

vector_longword_signed 

A homogeneous array whose elements are all 
signed longwords. 

vector_longword_unsigned 

A homogeneous array whose elements are all 
unsigned longwords. 

vector_quadword_signed 

A homogeneous array whose elements are all 
signed quadwords. 

vector_quadword_unsigned 

A homogeneous array whose elements are all 
unsigned quadwords. 

vector_word_signed 

A homogeneous array whose elements are all 
signed words. 

vector_word_unsigned 

A homogeneous array whose elements are all 
unsigned words. 

word_signed 

This VMS data type is the same as the data 
type "word integer (signed)" in Table 1-3. 

word-unsigned 

This VMS data type is the same as the data 
type "word (unsigned)" in Table 1-3. 
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1.4.3.2 Type Entry 

When a calling program passes an argument to a Run-Time Library 
procedure, the procedure expects the argument to be of a particular data 
type. The procedure descriptions in Part II indicate the expected data types 
for each argument. 

Properly speaking, an argument does not have a data type; rather, the data 
specified by an argument has a data type. The argument is merely the vehicle 
for the passing of data to the called routine. 

As described in the VAX Procedure Calling and Condition Handling Standard 
in Introduction to VAX/VMS System Routines , procedure calls result in the 
construction of an argument list. This argument list is a vector of longwords. 
The first longword on the list contains a count of the number of remaining 
longwords, and each remaining longword is one argument. Thus, an argument 
is one longword in the argument list. 

Nevertheless, the phrase "argument data type" is frequently used to describe 
the data type of the data that is specified by the argument. This terminology 
is used because it is simpler and more straightforward than the strictly 
accurate phrase "data type of the data specified by the argument". 

The following list contains the data types allowed by the VAX Procedure 
Calling and Condition Handling Standard. 


Table 1-3 VAX Data Types 

Data Type 

Absolute date and time 
Byte integer (signed) 

Bound label value 
Bound procedure value 
Byte (unsigned) 

COBOL intermediate temporary 

D_floating 

D_floating complex 

Descriptor 

F_floating 

F_floating complex 

G_floating 

G_floating complex 

H_floating 

H_floating complex 

Longword integer (signed) 

Longword (unsigned) 

Numeric string, left separate sign 
Numeric string, left overpunched sign 
Numeric string, right separate sign 
Numeric string, right overpunched sign 


Symbolic Code 

DSC$K_DTYPE_ADT 

DSC$K_DTYPE_B 

DSC$K_DTYPE_BLV 

DSC$K_DTYPE_BPV 

DSC$K_DTYPE_BU 

DSC$K_DTYPE_CIT 

DSC$K_DTYPE_D 

DSC$K_DTYPE_DC 

DSC$K_DTYPE_DSC 

DSC$K_DTYPE_F 

DSC$K_DTYPE_FC 

DSC$K_DTYPE_G 

DSC$K_DTYPE_GC 

DSC$K_DTYPE_H 

DSC$K_DTYPE_HC 

DSC$K_DTYPE_L 

DSC$K_DTYPE_LU 

DSC$K_DTYPE_NL 

DSC$K_DTYPE_NLO 

DSC$K_DTYPE_NR 

DSC$K_DTYPE_NRO 
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Table 1-3 (Cont.) VAX Data Types 


Data Type 


Symbolic Code 


DSC$K_DTYPE_NU 

DSC$K_DTYPE_NZ 

DSC$K_DTYPE_0 

DSC$K_DTYPE_OU 

DSC$K_DTYPE_P 

DSC$K_DTYPE_Q 

DSC$K_DTYPE_QU 

DSC$K_DTYPE_T 

DSC$K_DTYPE_V 

DSC$K_DTYPE_VT 

DSC$K_DTYPE_VU 

DSC$K_DTYPE_W 

DSC$K_DTYPE_WU 

DSC$K_DTYPE_Z 

DSC$K_DTYPE_ZEM 

DSC$K_DTYPE_ZI 


Numeric string, unsigned 
Numeric string, zoned sign 
Octaword integer (signed) 
Octaword (unsigned) 
Packed decimal string 
Quadword integer (signed) 
Quadword (unsigned) 
Character string 
Aligned bit string 
Varying character string 
Unaligned bit string 
Word integer (signed) 
Word (unsigned) 
Unspecified 
Procedure entry mask 
Sequence of instruction 


1.4.3.3 Access Entry 


The argument-access entry describes the way in which the called routine 
accesses the data specified by the argument. The following three methods of 
access are the most common. 

1 Read only. Data upon which a routine operates, or data needed by the 
routine to perform its operation, must be read by the called routine. Such 
data is also called input data. When an argument specifies input data, the 
"access" entry shows "read only". 

The term "only" is present to indicate that the called routine does not both 
read and write (that is, "modify") the input data. Thus, input data supplied 
by a variable is preserved when the called routine completes execution. 

2 Write only. Data that the called routine returns to the calling routine must 
be written into a location where the calling routine can access it. Such 
data is also called output data. When an argument specifies output data, 
the "access" entry shows "write only". 

The term "only" is present to indicate that the called routine does not read 
the contents of the location either before or after it writes into the location. 

3 Modify. When an argument specifies data that is both read and written 
by the called routine, the "access" entry shows "modify". In this case, the 
called routine reads the input data, which it uses in its operation, and 
then overwrites the input data with the results (the output data) of the 
operation. Thus, when the called routine completes execution, the input 
data specified by the argument is lost. 
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The following is a complete list of the access types allowed by the VAX 
Procedure Calling and Condition Handling Standard. 

• Read only 

• Write only 

• Modify 

• Function call (before return) 

• JMP after unwind 

• Call after stack unwind 

• Call without stack unwind 


1.4.3.4 Mechanism Entry 

The way in which an argument specifies the actual data to be used by the 

called routine is defined in terms of the argument passing mechanism. There 

are three types of passing mechanism. 

1 By value. When the longword argument in the argument list contains the 
actual data to be used by the routine, the actual data is said to be passed 
to the routine "by value". In this case, the longword argument contains 
the actual data; in other words, the argument is the actual data. Note that 
since an argument is only one longword in length, only data that can be 
represented in one longword can be passed by value. 

2 By reference. When the longword argument in the argument list contains 
the address of the data to be used by the routine, the data is said to be 
passed "by reference". In this case, the argument is a pointer to the data. 

3 By descriptor. When the longword argument in the argument list contains 
the address of a descriptor, the data is said to be passed "by descriptor". 

A descriptor consists of two or more longwords (depending on the type 
of descriptor used), which describe the location, length, and data type of 
the data to be used by the called routine. In this case, the argument is a 
pointer to a descriptor that itself is a pointer to the actual data. 

Figure 1-2 illustrates the three passing mechanisms. 
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Figure 1-2 Procedure Argument Passing Mechanisms 




DATA 



LENGTH 


Note: ARG 1, ARG 2, ARG N 
can be passed by value, by 
reference, or by descriptor 
in any of the above examples. 

:(AP) = argument pointer 

N = number of arguments 


ZK-1962-84 


1-29 























































Introduction 

Documentation Format for Run-Time Library Routines 


Table 1-4 contains a list of the the passing mechanisms allowed by the VAX 
Procedure Calling and Condition Handling Standard: 


Table 1-4 Passing Mechanisms 


Passing Mechanism 

Descriptor Code 

By value 


By reference 


By reference, array reference 


By descriptor 


By descriptor, fixed-length 

DSC$K_CLASS_S 

By descriptor, dynamic string 

DSC$K_CLASS_D 

By descriptor, array 

DSC$K_CLASS_A 

By descriptor, procedure 

DSC$K_CLASS_P 

By descriptor, decimal string 

DSC$K_CLASS_SD 

By descriptor, noncontiguous array 

DSC$K_CLASS_NCA 

By descriptor, varying string 

DSC$K_CLASS_VS 

By descriptor, varying string array 

DSC$K_CLASS_VSA 

By descriptor, unaligned bit string 

DSC$K_CLASS_UBS 

By descriptor, unaligned bit array 

DSC$K_CLASS_UBA 

By descriptor, string with bounds 

DSC$K_CLASS_SB 

By descriptor, unaligned bit string 

DSC$K_CLASS_UBSB 

with bounds 



1.4.3.5 Explanatory Text Entry 

For each argument, one or more paragraphs of explanatory text follows the 
"type", "access", and "mechanism" entries. The first paragraph is highly 
structured and always contains the following items of information. 

1 An initial sentence fragment that describes: (1) the nature of the data 
specified by the argument and (2) the way in which the routine uses this 
data. For example, if an argument were supplying a number, which the 
routine was to convert to another data type, the initial sentence fragment 
would be something like the following: "number that is to be converted to 
the such-and-such data type." 

2 A sentence expressing the relationship between the argument and the data 
that it specifies. This relationship is the passing mechanism used to pass 
the data. 

If the passing mechanism is "by value", this sentence says something like 
the following: "the xxx argument contains (or is) the such-and-such data." 

If the passing mechanism is "by reference", this sentence says something 
like the following: "the xxx argument is the address of the such-and-such 
data." 

If the passing mechanism is "by descriptor", this sentence says something 
like the following: "the xxx argument is the address of a descriptor 
pointing to the such-and-such data." 
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Additional explanatory paragraphs appear for each argument as needed. 

For example, some arguments specify complex data consisting of many 
discrete fields, each of which has a particular purpose and use. In such 
cases, additional paragraphs provide detailed descriptions of each such field, 
symbolic names for the fields, if any, and guidance relating to their use. 


1.4.4 Condition Values Returned Heading 

A condition value is an unsigned longword that has several uses in the VAX 
architecture. 

• It indicates the success or failure of a called procedure. 

• It describes an exception condition when an exception is signaled. 

• It identifies system messages. 

• It reports program success or failure to the command language level. 

The documentation heading "Condition Values Returned" describes the 
condition values returned by the routine when it completes execution 
without generating an exception condition. This condition value describes 
the completion status of the operation. 

If a called routine generates an exception condition during execution, the 
exception condition is signaled ; the exception condition is then handled by 
a condition handler (either user-supplied or system-supplied). Depending 
on the nature of the exception condition and on the condition handler that 
handles the exception condition, the called routine will either continue normal 
execution or terminate abnormally. 

If a called Run-Time Library routine executes without generating an exception 
condition, the called routine either returns a condition value or signals an 
error condition; a few procedures both return a condition value and signal 
an error condition. In the documentation of each routine, the method used 
to return the condition value is indicated in the heading title itself. These 
heading titles are discussed individually in the subsections which follow. 

Under either of these headings, a 2-column list gives the symbolic code 
for each condition value that the routine can return and its accompanying 
description. This description explains whether the condition value indicates 
success or failure, and if failure, what user action may have caused the failure 
and what can be done to correct it. Condition values that indicate success are 
listed first. 

Symbolic codes for condition values are system defined. The symbolic code 
defined for each condition value equates to a number that is identical to the 
longword condition value when interpreted as a number. In other words, 
though the condition value consists of several fields, each of which can be 
interpreted individually for specific information, the entire longword condition 
value itself can be interpreted as an unsigned longword integer, which has an 
equivalent symbolic code. 

The following subsections discuss the ways in which the called routine 
returns condition values. 
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1.4.4.1 Condition Values Returned 

When the called routine returns a condition value in general register RO, the 
possible condition values that the routine can return are listed under the 
"Condition Values Returned" heading. Most routines return a condition value 
in this way. 


1.4.4.2 Condition Values Signaled 

When the called routine signals its condition value (instead of returning it in 
RO), the possible condition values that the routine can signal are listed under 
the "Condition Values Signaled" heading. 

Routines that signal condition values as a way of indicating the completion 
status do so because these routines are returning actual data in one or more 
of the general registers. Since register RO is used to convey data, it cannot 
also receive the condition value. 

As mentioned, the signaling of condition values occurs whenever a routine 
generates an exception condition, regardless of how the routine returns its 
completion status under normal circumstances. 
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The VAX Procedure Calling and Condition Handling Standard, which is 
described in the Introduction to VAX/VMS System Routines , defines the 
interface between your program and the Run-Time Library procedures that 
your program calls. 

In order to conform to this standard, all of the VAX native-mode compiled 
languages provide mechanisms for coding calls to Run-Time Library 
procedures. This section describes in general how to call procedures on 
VAX/VMS. 

When you include a call to a library procedure in your program, you must 
furnish whatever arguments the procedure requires. In most cases, when 
the procedure completes execution, it returns control to your program. If 
the procedure returns a status code, your program should analyze the value 
of the code to determine the success or failure of the procedure so it can, if 
necessary, change the flow of execution. 

2.1 Overview 

When you log in, VAX/VMS creates a process which exists until you log out. 
When you run a program, VAX/VMS activates an executable image in your 
process. This image consists of a set of user procedures. 

From the Run-Time Library's point of view, user procedures are procedures 
outside the library that can call the library. User procedures can call both 
other user procedures and library procedures. User procedures can be either 
supplied by DIGITAL or written by you. To the library, a VAX native-mode 
language compiler is a set of user procedures, since it generates code that 
calls the Run-Time Library procedures implicitly. When you write a program 
that calls a Run-Time Library procedure explicitly, your program is considered 
a user procedure. 

The main program , or main procedure, is the first user procedure that the 
system calls after calling a number of initialization procedures. The term user 
program refers to the main program and all of the other user procedures that 
it calls. 

Figure 2-1 shows the calling relationships among a main program, other user 
procedures, library procedures, and VAX/VMS. In this figure, CALL indicates 
that the calling procedures requested information or action; RETURN 
indicates that the called procedure returned the information to the calling 
procedure or performed the action. 

Library procedures can call other library procedures or VAX/VMS. A library 
procedure can call user procedures only in the following cases: 

• When a library initialization procedure must be executed before the main 
program gets control. In this case, the library procedure LIB$INITIALIZE 
calls the initialization procedures that you have specified and then calls 
the main program (see Section 10). 
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Figure 2-1 Calling the Run-Time Library 
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• When a user procedure establishes its own condition handler. For 
example, LIB$SIGNAL operates by searching for and calling user 
procedures that have been established as condition handlers (see 
Section 7). 

• When a user procedure passes to the library the address of another 
procedure that the library will call later. For example, when your program 
calls LIB$SHOW_TIMER, you can pass as an argument an action routine 
that LIB$SHOW_TIMER will call to process timing statistics. 


2.2 Call Formats 


Each procedure requires a specific calling sequence. The calling sequence 
indicates the elements that you must include in the language statement that 
invokes the procedure, and the order of those elements. The form of a calling 
sequence is explained below. 

Call Type 

A calling sequence first specifies the type of call being made. A library 
procedure can be invoked by a CALLS or CALLG instruction or by a JSB 
instruction. Note that the following restrictions apply. 

• High-level languages do not differentiate between CALLS and CALLG. 
They use a CALL statement or a function reference to invoke a Run-Time 
Library procedure. 

• MACRO does not differentiate between functions and subroutines in its 
CALLS and CALLG instructions. 

• Only MACRO and BLISS programs can explicitly access the JSB entry 
points that are provided for some procedures in the Run-Time Library. 
You cannot write a program to access the JSB entry points directly 
from a high-level language. However, you should note that most 
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high-level language compilers do access the JSB entry points when they 
call Run-Time Library routines to provide built-in functions within the 
language. For example, when FORTRAN executes the SQRT function, it 
actually executes a Run-Time Library procedure by accessing the JSB entry 
point explicitly. 

Library Facility Prefix and Procedure Name 

Each procedure is identified by a unique entry point name, consisting of 
the library facility prefix (LIB$, MTH$, and so on) plus the procedure name 
(for example, MTH$SIN). Section 2.3 provides more detailed information on 
library naming conventions. 


Argument List 

Arguments passed to a procedure must be listed in your program in the 
order shown in the format section of the routine description. Each argument 
has four characteristics: VMS Usage, data type, access type, and passing 
mechanism. 


Some arguments are optional. Optional arguments are indicated by brackets 
in the procedure descriptions. When your program invokes a library 
procedure using a CALL entry point, you can omit optional arguments at the 
end of the argument list. If an optional argument is not at the end of the list, 
you must indicate its place in the list with a null entry or a zero. (This differs 
from calls to VAX/VMS System Services.) 

Optional arguments apply only to the CALL entry points. JSB entry points do 
not have optional arguments; all specified registers are used. 

For example, the call format for a procedure with two optional arguments is: 

LIB$GET_INPUT get-str [.prompt-str] [,out-len] 


A FORTRAN program could include any one of the following calls to this 
procedure: 


STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 
STAT = LIB$GET_INPUT 


(GET.STR,PROMPT,LENGTH) 
(GET.STR,PROMPT) 
(GET.STR,PROMPT,) 
(GET.STR,.LENGTH) 
(GET.STR) 

(GET.STR,) 

(GET.STR, */.VAL(0),) 


In MACRO, a calling sequence takes one of three forms, as illustrated by the 
following examples: 

CALLS #2,G~LIB$GET_INPUT 

CALLG ARGLIST, G~LIB$GET_VM 

JSB G~MTH$SIN_R4 


In other languages, you use the standard mechanism for calling an external 
procedure, subroutine, or function, as shown by the following examples: 


BLISS 


LOCAL 

MSG.DESC : BLOCK [8.BYTE]; 

MSG.DESC [DSC$B_CLASS] = DSC$K_CLASS_S; 
MSG.DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T; 
MSG.DESC [DSC$W_LENGTH] = 5; 

MSG.DESC [DSC$A_P0INTER] = MSG; 

STATUS = LIB$PUT_OUTPUT(MSG.DESC); 
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FORTRAN 

CALL LIB$M0VTC(SRC. FILL, TABLE, DEST) 

STATUS = LIB$GET_INPUT(STRING, 'NAME:') 

BASIC 

CALL LIB$M0VTC(SRC, FILL, TABLE, DEST) 

STATUS = LIBIGET.INPUT(STRING, 'NAME:') 

PL/I 

CALL LIB$MOVTC(SRC, FILL, TABLE, DEST); 

STATUS = LIBSGET.INPUT(STRING. 'NAME:'); 

COBOL 

CALL LIB$MOVTC USING BY DESCRIPTOR 
SRC. 

FILL. 

TABLE. 

DEST, 

GIVING RET-STATUS. 

PASCAL 

RET-STATUS := LIB$M0VTC (SRC. FILL, TABLE, DEST); 

As these examples show, VAX languages use varying call forms. Each 
language user's guide gives specific information on calling the Run-Time 
Library from that language. 


2.3 Run-Time Library Naming Conventions 

This section explains the naming conventions that the Run-Time Library 
follows for its entry point names, return status codes, and condition value 
symbols. 


2.3.1 Entry Point Names 

Run-Time Library entry points follow the VAX conventions for naming global 
symbols. A global entry point takes the following general form: 

fac$symbol 

The elements which make up this format represent the following: 

fac is a 2- or 3-character facility name, 

symbol is a 1- to 27-character symbol. 

The facility names are maintained in a system-wide DIGITAL registry. A 
unique, 12-bit facility number is assigned to each facility name for use in: 

(1) condition value symbols, and (2) condition values in procedure return 
status codes, signaled conditions, and messages. The high-order bit of this 
number is zero for facilities assigned by DIGITAL and 1 for those assigned by 
Computer Special Services (CSS) and customers. For further information, see 
The VAX Procedure Calling and Condition Handling Standard, which is fully 
described in the Introduction to VAX/VMS System Routines. 
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Table 2-1 lists the library facility prefixes and their associated facility 
numbers. 


Table 2-1 Library Facility Prefixes 


Name 

Number 

Facility Description 

LIBS 

21 

General purpose procedures 

MTHS 

22 

Mathematics procedures 

OTSS 

23 

Language-independent support procedures 

SMGS 

18 

Screen management procedures 

STR$ 

36 

String manipulation procedures 


2.3.2 JSB Entry Point Names 

JSB entry point names follow the naming conventions explained in the 
previous section, except that they include the number of the highest register 
accessed or modified. This helps ensure that the calling program and the 
called procedure will agree about the number of registers that the called 
procedure is going to change. 

The following example illustrates the MACRO code that invokes the library 
procedure MTH$SIN_R4 by means of a JSB instruction. This procedure uses 
RO through R4. 

JSB G~MTH$SIN_R4 ;F_lloating sine uses RO to R4 

JSB entry points are available only to MACRO and BLISS programs. No VAX 
high-level language provides a mechanism for accessing JSB entry points 
explicitly. 


2.3.3 Function Return Values 

Some Run-Time Library procedures return a function value. This is generally 
a 32-bit value returned in register RO or a 64-bit value returned in registers 
R0/R1. When a procedure returns a function value, it cannot use RO and R1 
to return a status code. Therefore, such a procedure signals errors rather than 
returning a status. 

Statuses or function return values in RO appear as the function result in 
high-level languages. 


2.3.4 Library Return Status and Condition Value Symbols 

Library return status and condition value symbols have the following general 
form: 

fac$_abcmnoxyz 
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The elements which make up this format represent the following: 
fac is the 2- or 3-letter facility symbol. 

abc are the first three letters of the first word of the associated message. 

mno are the first three letters of the next word. 

xyz are the first three letters of the third word, if any. 


Articles and prepositions are not considered significant words in this format. 
If a significant word is only two letters long, an underscore character is used 
to fill out the third space. Some examples follow. Note that the VAX/VMS 
normal or success symbol is an exception to the convention just described. 


SS$_NORMAL 

LIB$_INSVIRMEM 

MTH$_ 

FLOOVEMAT 

OTS$_FATINTERR 

LIB$_SCRBUFOVF 


Routine successfully completed 
Insufficient virtual memory 

Floating overflow in mathematics library procedure 

Fatal internal error in a language-independent support 
procedure 

Screen buffer overflow 


2.3.5 Argument Passing Mechanisms 

A calling program passes an argument list of longwords to a called procedure; 
each longword specifies a single argument. The called procedure interprets 
each argument using one of three standard passing mechanisms: by value, by 
reference, or by descriptor. 


2.3.5.1 Passing Arguments by Value 

When your program passes an argument using the by value mechanism, 
the argument list entry contains the actual, uninterpreted 3 2-bit value of 
the argument. The value mechanism is usually used to pass constants. For 
example, to pass the constant 100 by value, the calling program puts 100 
directly in the argument list. 

All VAX high-level languages require you to specify the by value mechanism 
explicitly when you call a procedure that accepts an argument by value. 
FORTRAN, for example, uses the %VAL argument list built-in function, 
while COBOL uses the BY VALUE qualifier on the CALL [USING] statement. 

A FORTRAN program calls a procedure using the BY VALUE mechanism as 
follows: 

INCLUDE '($SSDEF)' 

CALL LIB$ST0P (*/.VAL(SS$_INTOVF) 

A BLISS program calls this procedure as follows: 

LIB$SIGNAL (SS$_INT0VF) 

The equivalent MACRO code is: 

PUSHL #SS$_INT0VF ; Push longword by value 

CALLS #1,G~LIB$SIGNAL ; Call LIB$SIGNAL 

Note: Because the Run-Time Library is intended to be called from higher- 

level languages, most language-independent library procedures receive 
arguments by reference, rather than by value, at their CALL entry points. 
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2.3.5.2 Passing Arguments by Reference 

When your program passes arguments using the by reference mechanism, 
the argument list entry contains the address of the location that contains the 
value of the argument. For example, if variable x is allocated at location 1000, 
which currently contains the value 100, the argument list entry will contain 
1000. 

Most languages pass scalar data by reference unless you specify another 
mechanism. Thus you simply name x as an argument, and the language 
automatically passes the address 1000 to the Run-Time Library procedure. 

A BLISS program calls a procedure using the by reference mechanism as 
follows: 

LIB$FLT_UNDER (7.REF(1)) 


The equivalent MACRO code is: 


ONE: 

.LONG 

1 

; Longword value 1 


PUSHAL 

ONE 

; Push address of longword 


CALLS 

#1,G~LIB$FLT_UNDER 

; Call LIB$FLT_UNDER 


2.3.5.3 Passing Arguments by Descriptor 

When a procedure specifies that an argument is passed by descriptor , the 
argument list entry must contain the address of a descriptor for the argument. 
This mechanism is used to pass more complicated data. A descriptor includes 
at least the following fields to describe data. 


Symbol 

Description 

DSC$W_LENGTH 

Length of data (or DSC$W_MAXSTRLEN, maximum length, 
for varying strings) 

DSC$B_DTYPE 

Data type 

DSC$B_CLASS 

Descriptor class code 

DSC$A_POINTER 

Address at which the data begins 


See the Introduction to VAX/VMS System Routines for the VAX Procedure 
Calling and Condition Handling Standard, which describes these fields in 
greater detail. 

The VAX high-level languages include extensions for passing arguments 
by descriptor. When you specify by descriptor in these languages, the 
compiler creates the descriptor, defines its fields, and passes its address to 
the Run-Time Library procedure. In some languages, by descriptor is the 
default passing mechanism for certain types of arguments. The language 
documentation will tell you the default passing mechanism for a particular 
data type and the language statement that specifies an alternative mechanism. 

In BASIC, for example, the default mechanism for passing strings is by 
descriptor. 

100 COMMON STRING GREETING = 30 
200 CALL LIB$PUT_SCREEN(GREETING) 

The default mechanism in COBOL, however, is by reference. Thus you must 
specify BY DESCRIPTOR in the CALL statement to pass a string argument 
from a COBOL program to a Run-Time Library procedure: 

CALL LIB$PUT_0UTPUT USING BY DESCRIPTOR GREETING. 
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In MACRO or BLISS, you must define the descriptor's fields explicitly and 
push its address onto the stack. Following is the MACRO code which 
corresponds to the previous examples. 


MSGDSC: .WORD LEN 

.BYTE DSC$K_DTYPE_T 
.BYTE DSC$K_CLASS_S 
.ADDRESS MSG 


DESCRIPTOR: DSC$W_LENGTH 
DSC$B_DTYPE 
DSC$B_CLASS 
DSC$A_POINTER 


MSG: .ASCII/Hello/ 

LEN * .-MSG 

.ENTRY EX1,~M<> 

PUSHAQ MSGDSC 

CALLS #1,G~LIB$PUT_OUTPUT 

RET 

.END EX1 


String itself 

Define the length of the string 

Push address of descriptor 
Output the string 


The equivalent BLISS code looks like this: 

MODULE BLISS1 (MAIN = BLISS1, ! Example of calling LIB$PUT_OUTPUT 

IDENT = '1-001'. 

ADDRESSING_M0DE(EXTERNAL = GENERAL)) = 

BEGIN 

EXTERNAL ROUTINE 

LIBlSTOP, ! Stop execution via signaling 

LIBlPUT.OUTPUT; ! Put a line to SYSlOUTPUT 

FORWARD ROUTINE 

BLISS1 : NOVALUE; 



LIBRARY 'SYS$LIBRARY:STARLET.L32'; 


ROUTINE BLISS1 

: NOVALUE * 

BEGIN 


Routine 



Allocate the necessary local storage. 

LOCAL 

STATUS, ! Return status 

MSG.DESC : BLOCK [8, BYTE]; ! Message descriptor 

BIND 

MSG = UPLITC'HELLO'); 


Initialize the string descriptor 


MSG.DESC [DSClB.CLASS] = DSC$K_CLASS_S; 
MSG.DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T; 
MSG.DESC [DSCIW.LENGTH] = 5; 

MSG.DESC [DSC$A.POINTER] = MSG; 


! Put out the string. Test the return status. 

! If it is not a success, then signal the RMS error. 

STATUS = LIBlPUT.OUTPUT(MSG.DESC); 

IF NOT .STATUS THEN LIB$ST0P(.STATUS); 

END; ! End of routine BLISS1 

END ! End of module BLISS1 

ELUDOM 
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2.4 Passing Scalars As Arguments 

When a value is to be passed to a Run-Time Library procedure as an input 
argument, it is usually passed by reference or by value. 

• General purpose procedures (LIB$) and mathematics procedures (MTH$) 
are most likely to be called explicitly from high-level languages, which 
normally pass arguments by reference. Thus procedures in these two 
facilities receive input scalars by reference. 

• The language-support procedures, such as those in the OTS$ and COB$ 
facilities, are more likely to be called implicitly from code generated by 
a language compiler. For this reason, these procedures generally receive 
input scalars by value. If your high-level language program calls these 
procedures explicitly, be sure to specify that arguments are passed by 
value. 

Output scalar arguments are usually passed by reference to Run-Time Library 
procedures. That is, the argument passed to the procedure is the address of a 
location where the procedure's scalar output will be stored. 


2.5 Passing Arrays As Arguments 

Arrays are passed to library procedures by reference or by descriptor. 

Sometimes, the procedure knows the length and dimensions of the array to 
be received, as in the case of the table passed to LIB$CRC_TABLE. Arrays 
such as this are normally passed by reference. 

In other cases, the procedure will actually analyze and operate on the input 
array. The procedure does not necessarily know the length or dimensions 
of such an input array. A descriptor is therefore necessary to provide the 
information the procedure needs to perform the function. 


2.6 Passing Strings As Arguments 

Strings are passed by descriptor to Run-Time Library procedures. The 
Run-Time Library procedure recognizes the following descriptors: 


Descriptor 

Descriptor Class Code 

Numeric Value 

Unspecified 

DSC$K_CLASS_Z 

0 

Fixed-length 

DSC$K_CLASS_S 

1 

Dynamic 

DSC$K_CLASS_D 

2 

Array 

DSC$K_CLASS_A 

4 

Scaled decimal 

DSC$K_CLASS_SD 

9 

Noncontiguous array 

DSC$K_CLASS_NCA 

10 

Varying-length 

DSC$K_CLASS_VS 

11 


Note 

For detailed information about descriptors, see the VAX Procedure Calling 
and Condition Handling Standard in the Introduction to VAX/VMS System 
Routines. 
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A Run-Time Library procedure writes strings according to the following three 
types of semantics: 

• Fixed-length, characterized by an address and a constant length 

• Varying-length, characterized by an address, a current length, and a 
maximum length 

• Dynamic, characterized by a current address and a current length 


2.7 Combinations of Descriptor Class and Data Type 

Some combinations of descriptor class and data type are not permitted, either 
because they are not meaningful or because the VAX Procedure Calling and 
Condition Handling Standard does not recognize them. Furthermore, the 
same function may be performed with more than one combination. This 
section describes the restrictions on the combinations of descriptor classes 
and data types. These restrictions help to keep procedure interfaces simple 
by allowing a procedure to accept a limited set of argument formats without 
sacrificing functional flexibility. 

Only interfaces generated by higher-level language processors and their 
run-time support need to conform to the restrictions described in this 
section. It does not document the valid combinations for products other 
than higher-level language processors. However, products that use interfaces 
with VAX higher-level languages should use this section as a guideline. As 
new languages are supported under VAX/VMS and as new features are added 
to currently supported languages, requiring new combinations of data type 
and descriptor class, the information in this section may change. 

Tables 2-2 to 2-4 show all possible combinations of descriptor class and data 
type. For example. Table 2-2 shows that your program can pass an argument 

to a Run-Time Library procedure whose descriptor class is DSC$K_CLASS_A 

(array descriptor) and whose data type is unsigned byte (DSC$K_DTYPE_ 
BU). The VAX Procedure Calling and Condition Handling Standard does not 
permit your program to pass an argument whose descriptor class is DSC$K_ 
CLASS—D (decimal string) and whose data type is unsigned byte. 
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Table 2-2 


Atomic Data Types and Descriptor Classes 





DSC$K CLASS 




_S 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_vs 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$K_DTYPE_0 

= 

26 

Yes 



Yes 


Yes 

Yes 






DSC$K DTYPE F 

= 

10 

Yes 



Yes 

Yes 

Yes 

Yes 

- 

- 

Yes 

Yes 

Yes 

DSC$K_DTYPE_D 

= 

11 

Yes 



Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

Yes 

DSC$K_DTYPE_G 

= 

27 

Yes 

- 

- 

Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE H 

= 

28 

Yes 

- 

- 

Yes 

Yes 

Yes 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE FC 

= 

12 

Yes 

- 

- 

Yes 

Yes 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K DTYPE DC 

= 

13 

Yes 

- 

- 

Yes 

Yes 

- 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_GC 

= 

29 

Yes 



Yes 

Yes 


Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_HC 

= 

30 











- 


DSC$K_DTYPE_CIT 

= 

31 

Yes 


- 

Yes 



Yes 

- 








Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


Notes follow Table 2—5. 
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Table 2-2 (Cont.) Atomic Data Types and Descriptor Classes 








DSC$K 

.CLASS 










_S 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_VS 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$K_DTYPE_Z 

= 

0 

Yes 



Yes 



Yes 



Yes 

Yes 


DSC$K DTYPE BU 

= 

2 

Yes 



Yes 

Yes 


Yes 



Yes 

Yes 


DSC$K DTYPE WU 

= 

3 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K_DTYPE_LU 

= 

4 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 

- 

Yes 

Yes 

- 

DSC$K_DTYPE_QU 

= 

5 

Yes 



Yes 



Yes 






DSC$K_DTYPE_OU 

= 

25 

Yes 

- 

- 

Yes 

- 

- 

Yes 

- 





DSC$K_DTYPE_B 

= 

6 

Yes 



Yes 

Yes 

Yes 

Yes 



Yes 

Yes 


DSC$K_DTYPE_W 

= 

7 

Yes 



Yes 

Yes 

Yes 

Yes 



Yes 

Yes 

Yes 

DSC$K_DTYPE_L 

= 

8 

Yes 



Yes 

Yes 

Yes 

Yes 



Yes 

Yes 

Yes 

DSC$K_DTYPE_Q 

= 

9 

Yes 

- 

- 

Yes 


Yes 

Yes 



- 




Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


Notes follow Table 2-5. 
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Table 2-3 String Data Types and Descriptor Classes 





DSC$K_CLASS 




_S 

_D 

_V 

_A 

_P 

_SD 

_NCA 

_VS 

_VSA 

_UBS 

_UBA 

_BFA 




= 1 

= 2 

= 3 

= 4 

= 5 

= 9 

= 10 

= 11 

= 12 

= 13 

= 14 

= 191 

DSC$K_DTYPE_V 

= 

1 

Yes 



Yes 



Yes 



Yes 

Yes 


DSC$K_DTYPE_T 

= 

14 

Yes 

Yes 


Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

Yes 

DSC$K_DTYPE_NU 

= 

15 

Yes 





Yes 

Yes 






DSC$K_DTYPE_NL 

= 

16 

Yes 





Yes 

Yes 






DSC$K_DTYPE_NLO 

= 

17 

Yes 





Yes 

Yes 






DSC$K_DTYPE_NR 

= 

18 

Yes 





Yes 

Yes 






DSC$K_DTYPE_NLR 

= 

19 

Yes 





Yes 

Yes 






DSC$K_DTYPE_NZ 

= 

20 

Yes 





Yes 

Yes 






DSC$K_DTYPE_P 

= 

21 

Yes 





Yes 

Yes 






DSC$K DTYPE VT 

= 

37 








Yes 

Yes 




DSC$K_DTYPE_VU 

= 

34 

* 

* 

* 

* 

* 

* 

. 

* 

* 

* 

* 

* 


Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


Notes follow Table 2 - 5 . zk -4266-85 
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Table 2-4 Miscellaneous Data Types and Descriptor Classes 



DSC$K CLASS 

_S 

= 1 

_D 

= 2 

_v 

= 3 

_A 

= 4 

_P 

= 5 

_SD 
= 9 

_NCA 
= 10 

_VS 

= 11 

_VSA 

= 12 

_UBS 

= 13 

_UBA 

= 14 

_BFA 

= 191 

DSC$K_DTYPE_ZI = 22 

Yes 





* 







DSC$K DTYPE ZEM = 23 

Yes 





* 







DSC$K_DTYPE_DSC = 3 

(See Note 3) 

- 

- 

- 

Yes 

- 

* 

Yes 

- 

- 

- 

- 

- 

DSC$K_DTYPE_BPV = 32 

Yes 





* 

Yes 






DSC$K_DTYPE_BLV = 33 

Yes 





* 

Yes 







Key 


Yes 

The Calling Standard allows this combination of class and data type. 

* 

No valid interpretation exists for this combination. 

- 

The Calling Standard forbids the use of this combination of class and data type. Higher-level 
languages and their run-time support must conform to this restriction. 


Notes follow Table 2-5. zk -4265-85 


Notes 

1 Class types DSC$K_CLASS_PI (6) and DSC$K_CLASS_JI (8) are 
considered obsolete. 

2 Class type DSC$K_CLASS_J (7) is reserved for use by the VAX Symbolic 
Debugger. 

3 A descriptor with data type DSC$K_DTYPE_DSC (24) points to a 
descriptor that has class DSC$K_CLASS_D (2) and data type DSC$K_ 
DTYPE—T (14). All other class and data type combinations in the target 
descriptor are reserved for future definition in the standard. 

4 DSC$K_CLASS_P is used by VAX FORTRAN. No new VAX languages 
will use it. 

5 The scale factor for DSC$K_CLASS_SD is always a decimal data type. It 
does not vary with the data type of the data described by the descriptor. 

6 For DSC$K_CLASS_UBS and DSC$K_CLASS_UBA the length field will 
specify the length of the data field in bits. For example, if the data type is 
unsigned word (DSC$K_DTYPE_WU), DSC$W_LENGTH equals 16. 
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2.8 Errors from Run-Time Library Procedures 

A procedure can indicate an error condition to the calling program either by 
returning a 32-bit condition value in RO as a completion code or by signaling 
the error. 

A completion code, also called a return status, is either a success (bit 0 = 1) 
or error condition value (bit 0 = 0). In an error condition value, the low-order 
3 bits specify the severity of the error. Bits 27 through 16 contain the facility 
number, and bits 15 through 3 indicate the particular condition. The high- 
order 4 bits are control bits. When the called procedure returns a condition 
value, the calling program can test RO and choose a recovery path. For more 
information on the condition value, see Section 7.1.2. 

When the completion code is signaled, the calling program must establish a 
handler to get control before taking action. (See Section 7 for a description of 
signaling and condition handling.) 

Each facility of the Run-Time Library has a convention for indicating errors 
to calling programs. Any exceptions to these conventions are noted in the 
procedure description. 

LIB Indicates errors by returning a condition value. 

MTH Indicates errors by signaling. 

OTS Indicates severe errors by signaling. When an OTS$ procedure truncates 
a string in the process of copying, it returns a function value indicating the 
number of bytes that were not moved to the destination string. 

SMG Indicates errors by returning a condition value. Only SMG$CURSOR_ 
COLUMN and SMG$CURSOR_ROW do not return a condition value. 

STR Returns errors in both forms. Severe errors, those judged to be 

programming errors or conditions which prevent the procedure from 
doing useful work, are signaled. Errors that can be corrected using default 
values or those judged to be not serious are returned as a status code. 

Table 2-5 summarizes these techniques. 
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Table 2-5 Error Handling by Run-Time Library Facilities 


Facility 

Characteristics of Error Handling 

Handling Method 
for 

Severe Errors 

Handling Method for 
String 

Truncation Errors 

Contents of RO—R5 
after 

Return from JSB 

LI B$ 

Return status 

Return status 
(SUCCESS or SEVERE) 

Status in RO 

OTS$ 

Signal 

Return number of 
unmoved bytes 
remaining in 

source 

MOVC5 Registers 

SMG$ 

Return status 

N/A 

N/A 

STR$ 

Signal 

Return Status 
(WARNING) 

Status in RO 

MTH$ 

Signal 

Not applicable 

Function value in 

R0/R1 


ZK-4264-85 


Note: Two STR$ procedures, STR$COMPARE and STR$COMPARE_EQL, 

return a function value instead of a return status. If they return, they are 
considered to have returned successfully. 


2.9 Calling a Library Procedure in MACRO 

This section describes how to code MACRO calls to library procedures using 
a CALLS, CALLG, or JSB instruction. The routine descriptions in Part II of 
this manual describe the entry points for each routine. You can use either 
a CALLS or a CALLG instruction to invoke a procedure with a CALL entry 
point. You must use a JSB instruction to invoke a procedure with a JSB entry 
point. All MACRO calls are explicitly defined. 


2.9.1 MACRO Calling Sequence 

All Run-Time Library Procedures have a CALL entry point. Many frequently 
used procedures also have a JSB entry point. In MACRO, you invoke a 
CALL entry point with a CALLS or CALLG instruction. To access a JSB entry 
point, use a JSB instruction. For a complete description of these hardware 
instructions, see the VAX-11 Architecture Reference Manual. 

Arguments are passed to CALLS and CALLG entry points by a pointer to 
the argument list. The only difference between the CALLS and CALLG 
instructions is: 
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• For CALLG, the calling program specifies the address of the argument list, 
which can be anywhere in memory. This list remains in memory upon 
return. 

Both call instructions have the same effect on the called procedure. 

The VAX-11 Architecture Reference Manual contains detailed information 
about the operation of CALLS and CALLG instructions and about VAX 
procedure stack architecture. This information is particularly important when 
you want to control signaling and condition handling. 

JSB instructions execute faster than CALL instructions. They do not set up 
a new stack frame, do not change the enabling of hardware traps or faults, 
and do not preserve the contents of any registers before modifying them. For 
this reason, you must be careful when invoking a JSB entry point in order to 
prevent the loss of information stored by the calling program. 

Whichever type of call you use, the actual reference to the procedure entry 
point should use general mode addressing (G~). This ensures that the linker 
and the image activator will be able to locate the module within the shareable 
image. 

In most cases, you have to tell a library procedure where to find input values 
and store output values. You must select a data type for each argument when 
you code your program. Most procedures accept and return 32-bit arguments. 

For input arguments of byte, word, or longword values, you can supply 
either a constant value, a variable name, or an expression in the library 
procedure call. If you supply a variable name for the argument, the data type 
of the variable must be as large or larger than the data types that the called 
procedure requires. If, for example, the called procedure expects a byte in the 
range 0 to 100, you can use a variable data type of a byte, word, or longword 
with a value between 0 and 100. 

For each output argument, you must declare a variable of exactly the length 
required to avoid extraneous data. If, for example, the called procedure 
returns a byte value to a word-length variable, the left-most eight bits of 
the variable (15:8) are not overwritten on output. Conversely, if a procedure 
returns a longword value to a word-length variable, it modifies variables in 
the next higher word. 


2.9.2 CALLS Instruction Example 

When you use a CALLS instruction, push the arguments on the stack before 
the CALLS. Arguments are pushed in reverse order; the last argument listed 
in the calling sequence is pushed first. The following example shows how 
a MACRO program calls the procedure that allocates virtual memory in the 
program region for LIB$GET_VM. 
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.PSECT 

DATA 

PIC,USR,CON,REL,GBL,NOSHR,NOEXE,RD,WRT,NOVEC 

MEM: 

.LONG 

0 


; longword to hold address of 
; allocated memory 

LEN: 

.LONG 

700 


; Number of bytes to allocate 


.PSECT 

CODE 

PIC,USR,CON,REL,GBL,SHR,EXE,RD,NOWRT,NOVEC 


.ENTRY 

PROG, “M<> 



PUSHAL 

MEM 


Push address of longword 
to receive address of block 


PUSHAL 

LEN 


Push address of longword 
containing number of bytes 
desired 


CALLS 

#2, 

G“LIB$GET_VM 

Allocate memory 


BLBC 

RET 

R0, 

1$ 

Branch if memory not available 

1$: 

PUSHL 

R0 


; Signal the error 


CALLS 

RET 

#1. 

G“LIB$SIGNAL 



.END 

PROG 



Because the stack grows toward location 0, arguments are pushed onto the 
stack in reverse order from the order shown in the general format for the 
routine. Thus, the base-adr argument, here called START, is pushed first, 
and then the num-bytes argument, called LEN. Upon return from 
LIB$GET_VM, the calling program tests the return status (ret-status), which 
is returned in R0 and branches to an appropriate error routine if an error 
occurred. 


2.9.3 CALLG Instruction Example 

When you use the CALLG instruction, the arguments are set up in any 
location, and the call includes a reference to the argument list. The following 
example of a CALLG instruction is equivalent to the preceding CALLS 
example. 


ARGLST: 



.LONG 


2 

Argument list count 


.ADDRESS 

LEN 

Address of longword containing 





the number of bytes to allocate 


.ADDRESS 

START 

Address of longword to receive 





the starting address of the 
virtual memory allocated. 

LEN: 

.LONG 


20 

Number of bytes to allocate 

START: 

.BLKL 


1 

Starting address of the virtual 
memory. 


CALLG 

ARGLIST, G“LIB$GET_VM 

Get virtual memory 


BLBC 

R0, 

ERROR 

Check for error 


BRB 

10$ 




2.9.4 JSB Entry Points 

A procedure's JSB entry point name indicates the highest numbered register 
that the procedure modifies. Thus a procedure with a suffix Rn modifies 
registers R2 through Rn. You should always assume that R0 and R1 are 
modified. The calling program loads the arguments in registers before the JSB 
instruction is executed. 

A calling program must use a JSB instruction to invoke a library procedure 
by means of its JSB entry point. You pass arguments to a JSB entry point by 
placing them in registers in the following manner. 
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NUM: .FLOAT 

MOVF 
JSB 


0.7853981 
NUM, RO 
G~MTH$SIN_R4 


Constant Pl/4 

Set up input argument 

Call F.floating sine procedure 

Return with value in RO 


In this example, R4 in the entry point name indicates that MTH$SIN_R4 
changes the contents of registers RO through R4. The routine does not 
reference or change the contents of registers R5 through Rll. 

The entry mask of a calling procedure should specify all the registers to be 
saved if the procedure invokes a JSB routine. This step is necessary because a 
JSB procedure does not have an entry mask, and thus has no way to specify 
registers to be saved or restored. 


For example, consider program A calling procedure B by means of a CALL 

entry point. 

• Procedure B modifies the contents of R2 through R6, so the contents of 
these registers are preserved at the time of the CALL. 

• Procedure B then invokes procedure C by means of a JSB entry point. 

• Procedure C modifies registers RO through R 7. 

• When control returns to procedure B, R7 has been modified, but when 
procedure B passed control back to procedure A, it restores only R2 
through R6. Thus the contents of R7 are unpredictable, and program A 
will not execute as expected. Procedure B should be rewritten so that R2 
through R7 are saved in procedure B's entry mask. 


A similar problem occurs if the stack is unwound, since unwinding the 
stack restores the contents of registers for each stack frame as it removes the 
previous frame. Because a JSB entry point does not create a stack frame, the 
contents of the registers before the JSB instruction will not be restored unless 
they have been saved in the entry mask of the calling program. You do this 
by naming the registers to be saved in the calling program's entry mask, so a 
stack unwind correctly restores all registers from the stack. In the following 
example, the function Y=PROC(A,B) returns the value Y, where 
Y = SIN(A)*SIN(B). 


.ENTRY 

PROC, ~M <R2 

MOVF 

<D4(AP), RO 

JSB 

G'MTH$SIN_R4 

MOVF 

RO , R5 

MOVF 

<D8(AP) , RO 

JSB 

G~MTH$SIN_R4 

MULF 

R5 . RO 

RET 



Save R2:R5 
RO = A 
RO = SIN(A) 

Copy result to register 
not modified by MTH$SIN 
RO = B 
RO = SIN(B) 

RO = SIN(A)SIN(B) 

Return 


2.9.5 Return Status 


Your MACRO program can test for errors by examining segments of the 
32-bit status code returned by a Run-Time Library procedure. 

To test for errors, check for a zero in bit zero, using a Branch on Low Bit Set 
(BLBS) or Branch on Low Bit Clear (BLBC) instruction. 

To test for a particular condition value, compare the 32 bits of the return 
status with the appropriate return status symbol, using a Compare Long 
(CMPL) instruction or the Run-Time Library procedure LIB$MATCH_COND. 
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There are three ways to define a symbol for the condition value returned by 
a library procedure so that you can compare the value in RO with a particular 
error code: 

• Using the .EXTRN symbol directive. This causes the assembler to generate 
an external symbol declaration. 

• Using the $facDEF macro call. Calling the $LIBDEF macro, for example, 
causes the assembler to define all LIB$ condition values. 

• By default. The assembler automatically declares the condition value as 
an external symbol that is defined as a global symbol in the Run-Time 
Library. 


The following example asks for the user's name. It then calls the Run-Time 
Library procedure LIB$GET_INPUT to read the user's response from the 
terminal. If the string returned is longer than 30 characters (the space 
allocated to receive the name), LIB$GET_INPUT returns in RO the condition 
value equivalent to the error LIB$_INPSTRTRU, 'input string truncated.' This 
value is defined as a global symbol by default. The example then checks 
for the specific error by comparing LIB$_INPSTRTRU with the contents of 
RO. If LIB$__INPSTRTRU is the error returned, the program considers that 
the procedure executed successfully. If any other error occurs, the program 
handles it as a true error. 


$SSDEF 
IDSCDEF 
.PSECT $DATA 


PROMPT.D: 


.WORD 

.BYTE 

.BYTE 


PROMPT.LEN 

DSC$K_DTYPE_T 

DSC$K_CLASS_S 


.ADDRESS PROMPT 
PROMPT: .ASCII /NAME: / 
PROMPT.LEN = . - PROMPT 


STR.LEN = 30 
STRING.D: 

.WORD 
.BYTE 
.BYTE 
.ADDRESS STR.AREA 
STR.AREA: .BLKB STR.LEN 


STR.LEN 

DSC$K_DTYPE_T 

DSC$K_CLASS_S 


.PSECT $C0DE 
.ENTRY START , ‘M<> 
PUSHAQ PROMPT.D 


PUSHAQ STRING.D 


CALLS 

BLBS 

CMPL 

BEQL 

PUSHL 

CALLS 

10$: MOVL 

RET 

.END 


#2 , G~LIB$GET_INPUT 
RO , 10$ 

RO . #LIB$.INPSTRTRU 

10 $ 

RO 

#1 , G~LIB$SIGNAL 
#SS$_N0RMAL . RO 


START 


Define SS$ Symbols 
Define DSC$ Symbols 

Descriptor for prompt 
Length field 
Type field is text 
Class field is string 
Address 

String descriptor 
Calculate length of 
string 

Use 30-byte string 
Input string descriptor 
Length field 
Type field in text 
Class field is string 
Address 

Area to receive string 


Push address of prompt 
descriptor 

Push address of string 
descriptor 

Get input string 
Check for success 
Error: Was it 
truncated string? 

No, more serious error 


; Success, or name too 
; long 
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2.9.6 Function Return Values in MACRO 

Function values are generally returned in RO (32-bit values) or R0:R1 (64-bit) 
values. A MACRO program can access a function value by referencing RO 
or R0:R1 directly. For functions that return a string, the address of the string 
or the address of its descriptor is returned in RO. If a function needs to 
return a value larger than 64 bits, it must return the value by using an output 
argument. 

There are some exceptions to these rules: 

• JSB entry points in the MTH$ facility return FLJloating values in R0-R3. 

• One procedure, MTH$SINCOS, returns two function values, the sine and 

the cosine of an angle. Depending on the data type of the function values, 
the function values are returned in the following registers: 

F_floating R0-R1 

D_floating or G_floating R0-R3 

H_floating R0-R7 

As in the case of output arguments, a variable declared to receive the function 
values must be exactly the same length as the value. 


2.10 Calling a Library Procedure in BLISS 

This section describes how to code BLISS calls to library procedures. A called 

procedure can return only one of the following: 

• No value. 

• A function value (typically, an integer or floating-point number). For 
example, MTH$SIN returns its result as an F_floating value in RO. 

• A return status (typically, a 3 2-bit condition value) indicating that 
the procedure has either executed successfully or failed. For example, 
LIB$GET_INPUT returns a return status in RO. If the procedure executed 
successfully, it returns SS$_NORMAL; if not, it returns one of several 
possible error condition values. BLISS treats the return status like any 
other value. 


2.10.1 BLISS Calling Sequence 

Scalar arguments are usually passed to Run-Time Library procedures by 
reference. Thus, when a BLISS program passes a variable, it appears with no 
preceding period in the procedure-call actual argument list. A constant value 
can be easily passed using the %REF built-in function. 

The following example shows how a BLISS program calls LIB$PUT__ 
OUTPUT. This procedure writes a record at the user's terminal. 
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MODULE SHOWTIME(IDENT=' 1-1' ‘/.TITLE'Print time', MAIN=TIMEOUT) = 
BEGIN 

LIBRARY 'SYS$LIBRARY:STARLET'; ! Defines System Services,etc. 

MACRO 

DESC []=y,CHARCOUNT('/.REMAINING) , ! VAX-11 string descriptor 

UPLIT BYTE ('/.REMAINING) */.; ! definition 

BIND 

FMTDESC=UPLIT( DESC('At the tone, the time will be ', 
*/,CHAR(7) , ' !%T* )); 

EXTERNAL ROUTINE 

LIB$PUT_OUTPUT: ADDRESSING.MODE(GENERAL); 

ROUTINE TIMEOUT 

BEGIN 
LOCAL 

TIMEBUF: VECTOR [2] , 

MSGBUF: VECTOR[80,BYTE], 

MSGDESC: BLOCK[8,BYTE], 

RSLT: WORD; 


! 64-bit system time 
! Output message buffer 
! Descriptor for message buffer 
! Length of result string 


! Initialize the fields of the string descriptor, 
i - 


END 

ELUDOM 


MSGDESC[DSC$B_CLASS]=DSC$K_CLASS 
MSGDESC[DSC$B_DTYPE]=DSC$K_DTYPE 
MSGDESC[DSC$W_LENGTH]=80; 

MSGDESC[DSC$A_POINTER]=MSGBUF[0] 


IGETTIM(TIMADR=TIMEBUF); ! 

$FAOL(CTRSTR=FMTDESC, ! 

OUTLEN=RSLT, ! 

OUTBUF=MSGDESC, 

PRMLST= y.REF (TIMEBUF) ) ; 

MSGDESC [DSC$W_LENGTH] = .RSLT; 


RETURN (LIB$PUT_OUTPUT(MSGDESC); 
END; 


.S; 

.T; 


Get time as 64-bit integer 

Format Descriptor 

Output length (only a word!) 

! Output buffer desc. 
! Address of 64-bit 
! time block 
! Modify output desc. 
! Return status 


2.10.2 Accessing a Return Status in BLISS 

BLISS accesses a function return value or condition value returned in RO as 
follows: 

STATUS = LIB$PUT_OUTPUT(MSG_DESC); 

IF NOT .STATUS THEN LIB$ST0P(.STATUS); 


2.10.3 Calling JSB Entry Points from BLISS 

Many of the library mathematics routines have JSB entry points. You can 
efficiently invoke these routines from a BLISS procedure using LINKAGE and 
EXTERNAL ROUTINE declarations as in the following example. 
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MODULE JSB_LINK (MAIN = MATH_JSB, ! Example of using JSB linkage 

IDENT = '1-001', 

ADDRESSING.MODE(EXTERNAL = GENERAL)) = 


BEGIN 

LINKAGE 

LINK_MATH_R4 

= JSB (REGISTER =0; ! input reg 

REGISTER = 0): ! output reg 

NOPRESERVE (0,1,2,3,4) 

NOTUSED (5,6,7,8,9,10,11); 

EXTERNAL ROUTINE 

MTH$SIND_R4 : 

LINK.MATH.R4; 

FORWARD ROUTINE 

MATH.JSB; 



LIBRARY 'SYS$LIBRARY:STARLET.L32'; 


ROUTINE MATH.JSB = 

! Routine 

BEGIN 

LOCAL 

INPUT.VALUE : 
SIN.VALUE; 

INITIAL ('/,E '30.0'), 


! + 

! Get the sine of single floating 30 degrees. The input, 30 degrees 
! is passed in RO, and the answer, is returned in RO. Registers 
! 0 to 4 are modified by MTH$SIND_R4. 

i - 

MTH$SIND_R4 (.INPUT.VALUE ; SIN.VALUE); 

RETURN SS$_N0RMAL; 


END; 

! End of routine 

END 

ELUDOM 

! End of module JSB.LINK 
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This section discusses the Run-Time Library procedures that perform 
terminal-independent screen management functions. The following lists 
contain all the the screen management procedures grouped according to their 
functions. 


Termtable Routines 

SMG$DEI TERM_T ABLE SMG$GET_NUMERIC_DAT A 

SMG$GET_TERM_DATA SMG$INIT_TERM_T ABLE 

SMG$INIT_TERM_TABLE_BY_TYPE 


Input Routines 


SMG$ADD_KEY_DEF 
SMG$CRE ATE_KEY_T ABLE 
SMG$DEFINE_KEY 

SMG$DELETE_VIRTUAI_KEYBOARD 

SMG$GET_KEYBOARD_ATTRIBUTES 

SMG$LOAD_KEY_DEFS 

SMG$READ_KEYSTROKE 

SMG$READ_VERIFY 

SMG$RETURN_INPUT_LINE 

SMG$SET_KEYPAD_MODE 


SMGSCANCEI_INPUT 

SMG$CREATE_VIRTUAL—KEYBOARD 
SMGSDELETE _KEY_DEF 
SMG$GET_KEY_DEF 
SMG$LIST_KEY_DEFS 
SMG$READ_COMPOSED_LINE 
SMG$READ_STRING 
SMG$REPLACE_INPUT_LINE 
SMG$SET_DEFAULT_ST ATE 


Output Routines 
SMG$BEGIN_DISPLAY_UPDATE 

SMG$CHANGE_PBD_ 
CHARACTERISTICS 

SMG$CHANGE_VIRTUAI_DISPLAY 

SMGSCONTROI_MODE 

SMGSCREATE-PASTEBOARD 

SMG$CURSOR_COLUMN 

SMG$DELETE_CHARS 

SMG$DELETE_PASTEBOARD 

SMGSDIS ABLE—BROADCAST— 
TRAPPING 

SMGSDRAW—LINE 
SMGSENABLE—UNSOLICITED—INPUT 
SMGSEND—PASTEBOARD—UPDATE 


SMGSBEGIN—PASTEBOARD—UPDATE 
SMGSCHANGE—RENDITION 

SMG$CHECK_FOR—OCCLUSION 

SMGSCOPY—VIRTU Al_DISPLAY 

SMGSCRE ATE—VIRTU Al_DISPLAY 

SMGSCURSOR—ROW 
SMGSDELETE—LINE 
SMGSDELETE—VIRTUAL—DISPLAY 
SMGSDISABLE—UNSOLICITED—INPUT 

SMGSDR A W_RECT ANGLE 
SMGSEND—DISPLAY—UPDATE 
SMGSERASE—CHARS 
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Output Routines 


SMG$ERASE_DISPLAY 
SMG$ERASE_PASTEBOARD 
SMG$FLUSH—BUFFER 

SMG$GET_CHAR_AT_PHYSICAL_ 

CURSOR 

SMG$GET_PASTEBOARD_ 

ATTRIBUTES 

SMG$GET_PHYSICAI_CURSOR 

SMG$INSERT_CHARS 
SMG$INVALID ATE—DISPLAY 

SMGSMOVE—VIRTU Al_DISPLAY 

SMGSPOP—VIRTUAL -DISPLAY 
SMGSPUT—CHARS—HIGHWIDE 
SMG$PUT_LINE 
SMGSPUT—LINE—WIDE 

SMGSPUT-VIRTUAL-DISPLAY- 
ENCODED 

SMGSREPAINT—LINE 

SMGSREP ASTE-VIRTU AL -DISPLAY 

SMGSRETURN—CURSOR—POS 

SMGSSAVE—PHYSIC Al_SCREEN 

SMGSSET—BRO ADC AST—TRAPPING 
SMGSSET—CURSOR—MODE 
SMGSSET-DISPL AY-SCROLL -REGION 
SMGSSET-PHYSICAL-CURSOR 
SMGSUNPASTE—VIRTUAL—DISPLAY 


SMGSERASE—LINE 
SMGSFIND—CURSOR—DISPLAY 
SMGSGET—BROADCAST—MESSAGE 
SMGSGET—DISPLAY—ATTR 

SMGSGET—PASTING—INFO 

SMGSHOME—CURSOR 
SMGSINSERT—LINE 
SMGSLABEL-BORDER 

SMGSPASTE—VIRTU Al_DISPLAY 

SMGSPUT—CHARS 
SMGSPUT—CHARS—WIDE 
SMGSPUT—LINE—HIGHWIDE 
SMGSPUT—PASTEBOARD 
SMGSREAD—FROM—DISPLAY 

SMGSREPAINT—SCREEN 
SMGSRESTORE—PHYSICAL—SCREEN 
SMGSRING—BELL 
SMGSSCROLL —DISPLAY—AREA 
SMGSSET—CURSOR—ABS 
SMGSSET—CURSOR—REL 
SMGSSET—OUT—OF_BAND—ASTS 
SMGSSNAPSHOT 


These procedures are meant for the types of operations you would normally 
perform on a VTlOO-class terminal; they also provide software emulation of 
screen management functions on terminals that do not have these functions 
implemented in their hardware. While these procedures are primarily 
intended for use with video terminals, they can also be used with hardcopy 
devices and files. Most important, these procedures assist you in designing, 
composing, and keeping track of complex images on a video screen. 


. 1 Overview of the Screen Management Facility 

The Screen Management Facility provides two important services. 

• Terminal Independence 

The screen management procedures provide terminal independence by 
allowing you to perform commonly needed screen functions without 
concern for the type of terminal being used. All operations, including 
input and output, are performed by calling a procedure that converts 
the caller's terminal-independent request (for example, to scroll a part of 
the screen) into the sequence of codes needed to perform that action. If 
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the terminal being used does not support the requested operation in the 
hardware, the screen management procedures accomplish the action by 
emulating it in software. Similarly, the screen management procedures 
provide a terminal-independent means for performing input from a 
keyboard without concern for the type of keyboard being used. 

• Composition Aids 

The screen management procedures assist you in composing complex 
images on a screen. For example, you may want to solicit user input from 
one part of the screen, display results on a second part of the screen, and 
maintain a status display in a third part of the screen. Normally, each 
routine that reads from or writes to one of these regions must be aware 
that other regions exist and know where on the screen they are positioned, 
in order to properly bias its row and column references to locate the 
display on the desired part of the screen. Using the screen management 
procedures, routines can independently write to their dedicated region of 
the screen without regard to the position of the region. Their references 
to rows and columns pertain only to the region of the screen they are 
addressing. 

The most important aspect of the Screen Management Facility is that user 
programs are entirely separate from the physical devices that actually perform 
input and output. Instead of writing directly to a physical screen, the user 
program writes to a virtual display. Similarly, instead of performing input 
directly from a physical keyboard, user programs perform input from a virtual 
keyboard. (Virtual displays and virtual keyboards are logical entities whose 
usage is described more fully in Section 3.2.) This separation of virtual 
operations from physical operations is what allows terminal-independent 
input/output to be realized. 

The following sections discuss the various features and operations that are 
part of the Screen Management Facility. 

• Section 3.2 describes pasteboards, virtual displays, and virtual keyboards. 

• Section 3.3 explains composition operations. 

• Section 3.4 discusses the output operations that can be performed on a 
virtual display. 

• Section 3.5 discusses the input operations that can be performed on a 
virtual keyboard. 

• Section 3.6 outlines two operational controls: minimal updating and 
buffering. 

• Section 3.7 explains two modes of operation for optimizing performance: 
display and pasteboard update batching. 

• Section 3.8 describes several advanced features: control of asynchronous 
actions, output to hardcopy terminals and files, and special features. 

• Section 3.9 provides guidelines for developing new programs that use 
screen management procedures. 

• Section 3.10 describes the use of the Screen Management Facility on 
non-DIGITAL terminals. 
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3.2 Pasteboards, Virtual Displays, and Virtual Keyboards 

The screen management procedures discussed in this section are used to 
create and delete fundamental elements in the screen management model, 
and to associate them with one another. These elements are the pasteboard, 
the virtual display, and the virtual keyboard. 


3.2.1 Pasteboards 


A pasteboard is a logical structure for performing output operations to a 
terminal screen. You can think of a pasteboard as a two-dimensional area 
on which you place and manipulate screen displays. A pasteboard is always 
associated with a physical device, but a pasteboard may be larger or smaller 
than the physical screen. There can be only one pasteboard for each output 
device. 

You create a pasteboard by calling the SMG$CREATE—PASTEBOARD 
procedure and specifying as an argument the physical device to be associated 
with the pasteboard. SMG$CREATE—PASTEBOARD returns as an output 
argument a unique pasteboard identifier (pasteboard-id), which is used in 
subsequent procedure calls where a pasteboard identifier is needed. For 
example, you use the pasteboard-id to specify the physical terminal screen 
on which to paste a virtual display. SMG$CREATE—PASTEBOARD also 
returns as output arguments the numbers of rows and columns available on 
the associated device. You can use this information to create a virtual display 
the size of the physical screen. 
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It is useful to think of a pasteboard as a logical coordinate system in which 
the relative orientation of one or more virtual displays is specified. Figure 
3-1 depicts the pasteboard coordinate system. 

Figure 3-1 Pasteboard Coordinate System 
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The cellular position (1,1) corresponds to the upper left-hand comer of the 
physical screen. The numbers of rows and columns visible on the screen start 
from this origin. For example, on a VT52, with 24 rows and 80 columns, the 
first 24 rows and first 80 columns of the pasteboard coordinate system map 
to the physical screen. Note that you can place a virtual display anywhere 
in this coordinate system, not only in the quadrant that corresponds to the 
physical screen. Thus a virtual display, when pasted (that is, positioned on 
the pasteboard), may be invisible or only partly visible on the physical screen. 


Pasteboards are deleted, or disassociated, from a particular device by the 
SMG$DELETE_PASTEBOARD procedure. When a pasteboard is deleted, all 
virtual displays pasted to it are unpasted. 

Once a pasteboard has been created, you can leam about its attributes 
(particularly its dimensions) by calling SMG$GET_PASTEBOARD_ 
ATTRIBUTES. You can change the characteristics of a pasteboard by calling 
SMG$CHANGE_PBD_CHARACTERISTICS—if the associated physical 
device allows the change. For example, if the device is a VT100, you can 
change the width of the pasteboard from 80 columns to 132 columns. 

When the pasteboard is created, the Screen Management Facility clears the 
screen by default; however, you can request that the screen be left as it is. In 
addition, you can call SMG$ERASE_PASTEBOARD to explicitly erase the 
screen. 


3.2.2 Virtual Displays 

A virtual display is a rectangular part of the terminal screen to which a 
program writes data with procedure calls. Virtual displays are the main focus 
of the Screen Management Facility. When you create images to be placed on 
the screen, you should think in terms of virtual displays rather than in terms 
of the physical screen. This logical separation of the virtual display from the 
physical screen allows a main program to reconfigure the positions of virtual 
displays, so that a subroutine that writes to the virtual display need not be 
involved with positioning the display on the physical screen. 
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When a virtual display is associated with a pasteboard, it is said to be 
pasted. When the display is removed from the pasteboard, it is said to be 
unpasted. A virtual display is invisible unless it is pasted to a pasteboard. 

(See Section 3.3.1 for more information on pasting virtual displays.) 

A program can create and maintain any number of virtual displays (limited 
only by the virtual address space available). A single virtual display can be 
pasted to more than one pasteboard at a time; thus, a program need maintain 
only the virtual display. Any change to a virtual display is automatically 
reflected in each pasteboard (and the associated terminal screen) to which the 
display is pasted. 

Virtual displays are created by a call to the SMG$CREATE_VIRTUAL— 
DISPLAY procedure. A call to this procedure must specify the number of 
rows and columns that make up the virtual display. The program may also 
request certain display and video attributes to be applied to the display. 

SMG$CREATE_VIRTUAL_DISPLAY returns as an output argument a unique 
virtual display identifier (display-id). This display-id is used to identify the 
virtual display on subsequent procedure calls that modify the display. 

A program or subroutine can determine which attributes and dimensions are 
associated with a virtual display by calling the SMG$GET_DISPLAY—ATTR 
procedure. 

Video attributes are the default characteristics, or rendition , to be applied 
to output when no other attributes have been specified. Renditions include 
bolding, blinking, reverse video, and underlined text. Display attributes are 
the characteristics that specify whether or not the display: 

• Is surrounded by a border (which may be labeled) 

• Echoes carriage-control characters (like form-feed, vertical tab, and so on) 

• Shows the user a diamond-shaped icon when text wraps past the 
rightmost position in the display 

The video and display attributes you specify when you create a virtual 
display can be changed. The SMG$CHANGE_RENDITION procedure lets 
you change video attributes while the SMG$CHANGE—VIRTUAL-DISPLAY 
procedure lets you change both video and display attributes. For example, 
you can redimension a virtual display with the latter procedure. When you 
redimension a virtual display, the data in it is copied to the redimensioned 
display; that is, as much of the current contents (starting with row 1, column 
1) as will fit in the newly dimensioned display are preserved. 

You can delete a virtual display by calling the SMG$DELETE_VIRTUAL- 
DISPLAY procedure. See Section 3.3.5 for more information on the delete 
operation. 
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3.2.3 Virtual Keyboards 

A virtual keyboard is a logical structure for input operations, just as a 
pasteboard is a logical structure for output operations. The advantage of 
using virtual keyboards is device independence. When using the screen 
management input procedures, you need not worry about the type of 
terminal being used. For example, your program need not know which line 
terminators a particular terminal uses; the screen management procedures 
map the different terminator character sequences into a uniform set of 
function codes. (See Section 3.5 for more information about terminator 
codes.) 

A virtual keyboard is usually associated with a physical keyboard on a 
terminal, but it may also be any file accessible through RMS. There is a 
one-to-one correspondence between a virtual keyboard and an input device 
or file. (The screen management input operations can be used with the 
output procedures or they can be used by themselves.) You establish a source 
for input (a virtual keyboard) by calling the SMG$CREATE_VIRTUAL- 
KEYBOARD procedure. You delete virtual keyboards by calling the 
SMG$DELETE_VIRTUAI ^KEYBOARD procedure. Once you have created 
a virtual keyboard, you can obtain data from it with the SMG$READ_ 
COMPOSED-LINE, SMG$READ_KEYSTROKE, SMG$READ_STRING, 
or SMG$READ_VERIFY procedures. SMG$READ_COMPOSED—LINE 
reads a line composed of ordinary keystrokes and predefined strings 
associated with keypad and control keys; it provides an easy way to code an 
interface for command-oriented utilities by providing single-key command 
capabilities. SMG$READ_KEYSTROKE is used to read one key entered at the 
keyboard. SMG$READ_STRING reads a string composed of characters and 
a terminator; this procedure is general purpose and flexible, providing access 
to many features of the VAX/VMS terminal driver. SMG$READ—VERIFY 
is used for reading formatted input. Both types of read operations can 
be cancelled before completion by calling the SMG$CANCEL_INPUT 
procedure. 


3.3 Composition Operations 

Composition operations are the procedures you use to manipulate virtual 
displays on a pasteboard and thus to create an image on a terminal screen. 
These operations include pasting, unpasting, repasting, moving, and popping 
virtual displays and checking virtual displays for occlusion. 


3.3.1 Paste Operation 

Virtual displays are visible on a physical device only while they are pasted to 
a pasteboard. Displays are pasted to a pasteboard by calling SMG$PASTE_ 
VIRTUAL-DISPLAY and specifying the pasteboard coordinates at which the 
display origin is to be placed. (The origin is the top left-hand comer.) The 
pasteboard itself has no boundaries, but of course the physical screen does. 
Thus you can paste a display to a pasteboard in such a way that some or all 
of the display does not appear on the terminal screen. 

Pasting virtual displays to a pasteboard is a logical operation which maps 
the contents of a virtual display to a location on the screen by specifying the 
row and column of the pasteboard that coincides with row 1 and column 
1 of the virtual display. For example, pasting a 6-row virtual display "A" to 
pasteboard rows 1 through 6 and pasting a second 6-row virtual display "B" 
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to pasteboard rows 7 through 12 places virtual display "B" immediately below 
virtual display "A" on the screen. See Figure 3-2. 

Figure 3-2 Paste Operation 
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3.3.2 Unpaste Operation 

A virtual display can be made to disappear from the physical screen with 
the SMG$UNPASTE_VIRTUAL_DISPLAY procedure. To continue the 
example in Section 2, if virtual display "B" is unpasted, the results appear as 
in Figure 3-3. 

Figure 3-3 Unpaste Operation 
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Unpasting a virtual display does not destroy the virtual display or its 
contents; it simply removes the display from the pasteboard on which it was 
pasted. 

Displays can overlap partially or completely, depending on the order in 
which they are pasted. This overlap is called occlusion. Unpasting the top 
display causes the underlying display(s) to be visible, and this change is 
reflected in the appearance of the screen. 


3.3.3 Repaste Operation 

You can move a virtual display to a new location on the pasteboard by calling 
SMG$REPASTE_VIRTUAL^DISPLAY, which prevents the screen from being 
left blank during the unpaste and repaste operations. Figure 3-4 below 
shows the effect of repasting the second display farther to the right. Notice 
that Display 2 has been pulled out of its former pasting order and is now 
the uppermost pasting—hiding part of Display 3, which was the uppermost 
display before the repasting operation. 

Figure 3-4 Repaste Operation 
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3.3.4 Move Operation 

You can also move a virtual display around the pasteboard while preserving 
its pasting order by calling the SMG$MOVE_VIRTUAL_DISPLAY procedure. 
Figure 3-5 shows the effect of moving the second display to the right. Note 
the difference between the unpaste and move operations: the pasting order 
does not change with a move. Thus, Display 2 remains partially occluded by 
Display 3. 
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Figure 3-5 Move Operation 
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3.3.5 Delete and Pop Operations 

The unpaste, repaste, and move operations shown thus far do not destroy 
the virtual displays affected. You can remove and delete a virtual display by 
calling the SMG$DELETE_VIRTUAL_DISPLAY procedure. You can also 
remove a number of virtual displays from a pasteboard and delete them in a 
single operation by calling SMG$POP_VIRTUAL_DISPLAY. This procedure 
unpastes and deletes the specified virtual display and all other virtual displays 
that were pasted after the one specified. 

The pop operation is useful in a modular environment. For example, you can 
call a subroutine and pass only the pasteboard-id upon which it is to produce 
output. The subroutine can then create additional virtual displays and paste 
them to the indicated pasteboard. When the subroutine returns control to 
its caller, the subroutine returns the display-id of the first virtual display it 
has pasted. The calling program can then undo the effects of the subroutine 
by calling SMG$POP_VIRTUAL_DISPLAY, passing the id of the virtual 
display returned by the subroutine. This technique minimizes the amount 
of information that needs to be passed between the calling program and its 
subroutine. Figure 3-6 shows the effects of popping display 2. 
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Figure 3-6 Pop Operation 
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3.3.6 Occlusion Check Operation 

It is sometimes useful to determine whether a display, as pasted on a given 
pasteboard, is occluded. You can find this out by calling the SMG$CHECK__ 
FOR—OCCLUSION procedure. For example, in the configuration represented 
in Figure 3-7, displays 1 and 2 would be reported as being occluded, while 
displays 3 and 4 would be reported as not occluded. Note that this test 
cannot be used to determine which display is pasted uppermost on the 
pasteboard; it can determine only whether or not the display, as pasted, is 
occluded. 

Figure 3-7 Occlusion Check 
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3.4 Output Through Virtual Displays 

This section describes the screen management procedures used to perform 
output through virtual displays. 

Writing to a virtual display is similar to writing directly to the terminal. 
However, writing to a virtual display is done entirely by calling screen 
management procedures. Erasing the screen, setting the cursor position, 
and scrolling output text are typical operations provided by the Screen 
Management Facility. Text is arranged in the virtual display's buffer, so the 
display need not be pasted before it can receive output. When you write 
to the physical screen, you are limited by the physical boundaries of the 
screen. Similarly, screen management output operations are confined to 
the boundaries of the virtual display: you cannot write text beyond the last 
column of a virtual display. 

Remember that changes to a virtual display are not seen on the screen unless 
the virtual display is pasted to the part of the pasteboard that is visible on the 
screen. If the virtual display is not pasted, or if it is pasted in a position that 
is not visible, such changes are reflected only in the internal database that 
represents the virtual display. 


3.4.1 Cursor Position 


When a virtual display is first created, the virtual cursor is positioned at row 
1, column 1 of the virtual display. Various output operations to the virtual 
display move the virtual cursor, just as output operations do to a physical 
terminal. 

The position of the virtual cursor in a virtual display should not be confused 
with the position of the physical cursor on the screen. There may be many 
virtual displays pasted to a pasteboard and hence visible at the same time on 
the physical screen. Although each virtual display has an associated virtual 
cursor position, only one of the virtual cursor positions for all these displays 
corresponds to the physical cursor—usually the cursor position of the virtual 
display that has been modified most recently. 

You can determine the current position of the virtual cursor within a virtual 
display by calling the SMG$RETURN_CURSOR_POS procedure. This 
procedure returns the current virtual cursor row and column as output 
arguments. 

For programming convenience, this information can also be obtained through 
two separate procedures, SMG$CURSOR_ROW and SMG$CURSOR_ 
COLUMN, which operate as functions. These two routines makes it easy to 
code constructions like this: 

IF SMG$CURSOR_ROW ( Display-id ) > Max-row 
THEN 
BEGIN 


END 
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To obtain this information with SMG$RETURN_CURSOR_POS, you would 
write the following. 

CALL SMG$RETURN_CURSOR_POS ( Display-id, Cursor-row, Cursor-column) 

IF Cursor-row > Max-row 
THEN 
BEGIN 


END 

SMG$RETURN_CURSOR__POS requires you to define two local variables. 
Cursor-row and Cursor-column, which you might not need except to perform 
this test. However, this procedure yields both the row and column in a single 
procedure call. 

The three following procedures are available to set the virtual cursor position 
in a virtual display. 

• The SMG$SET_CURSOR_ABS procedure sets the virtual cursor to the 

absolute display position specified. 

• The SMG$SET_CURSOR—REL procedure sets the virtual cursor position 
to the specified offset from the current display cursor position. 

• The SMG$HOME_CURSOR procedure sets the virtual cursor to the 
virtual display's "home" position (row 1, column 1). 


3.4.2 Deletion Operations 

Two procedures are provided to delete parts of a virtual display. 

SMG$DELETE_CHARS deletes one or more characters on a single line. 
Character positions removed by this procedure are replaced with the 
characters to the right of the deleted characters on the same line. Character 
positions opened at the end of the line are filled with blanks. 

SMG$DELETE_LINE deletes one or more entire lines. Lines removed by this 
procedure are filled by the lines immediately below the deleted lines. New 
lines introduced into the bottom of the virtual display are blank. 


3.4.3 Erasure Operations 

During an erase operation, the erased portion of the virtual display is filled 
with blanks. No other parts of the virtual display are rearranged. 

Three procedures are provided to erase parts of a virtual display. 

• SMG$ERASE_CHARS erases a specified number of characters within a 
given line. 

• SMG$ERASE_LINE erases characters in a line from the specified starting 
position to the end of the line. 

• SMG$ERASE_DISPLAY erases all or part of a virtual display. 
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3.4.4 Insertion Operations 

Two procedures are provided to insert text into a virtual display. 

SMG$INSERT_CHARS deposits the specified string of characters in the 
indicated starting position. Existing characters in these positions are shifted to 
the right to make room for each character as it is inserted. Characters shifted 
beyond the rightmost column are discarded. 

SMG$INSERT_LINE inserts the specified line of text in the position 
indicated. You can scroll existing lines in the virtual display up or down to 
make room for the inserted lines. Lines scrolled above the top line or below 
the bottom line of the virtual display are discarded. 


3.4.5 Writing Operations 

The Screen Management Facility provides two types of procedures for writing 
text to a virtual display: character-oriented output and line-oriented output. 
The sections which follow describe these procedures. 


3.4.5.1 Character-Oriented Output 

You typically use the character-oriented output procedures when using a 
virtual display as a direct-access device. In this mode of operation, the 
program explicitly sets the cursor in the virtual display and deposits text 
there. Since the next output operation usually has no spatial relationship to 
the previous one, you need to control the cursor position explicitly. 

There are three character-oriented output procedures: 

• SMG$PUT_CHARS, which writes normal characters to a virtual display 

• SMG$PUT_CHARS_WIDE, which writes double-width characters to a 
virtual display 

• SMG$PUT_CHARS_HIGHWIDE, which writes double-width, 
double-height characters to a virtual display 

Note that you cannot mix these different types of characters on a single line 
in a virtual display. 


3.4.5.2 Line-Oriented Output 

In contrast to the character-oriented output procedures, the line-oriented 
procedures treat a terminal as a sequential device. In this mode of 
operation, the program typically writes one line of information after another. 
Conceptually, this action corresponds to copying a stream of information (for 
example, a file) to a virtual display. Each procedure call leaves the cursor at 
column 1 of the next row after the operation is complete. 

There are three line-oriented output procedures: 

• SMG$PUT_LINE, which writes lines of text to a virtual display. 

• SMG$PUT_LINE_WIDE, which writes lines of double-width text to a 
virtual display. 

• SMG$PUT_WITH_SCROLL, which writes text to a virtual display 
beginning at the current line. Once text reaches the bottom or top line 
(depending on the scrolling direction), subsequent calls to this routine 
cause the display to scroll. 
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3.4.6 


Changing the Current Rendition of a Virtual Display 


When you create a virtual display with the SMG$CREATE_VIRTUAL_ 
DISPLAY procedure, you specify a default rendition for all text that appears 
in the virtual display. You can change the default rendition for an existing 
virtual display by calling either the SMG$CHANGE_VIRTUAL_DISPLAY or 
SMG$CHANGE_RENDITION procedures. 

The SMG$CHANGE_VIRTUAL_DISPLAY procedure lets you change display 
attributes as well as video attributes; the SMG$CHANGE_RENDITION 
procedure can be used to change the video rendition of text that is already 
in the virtual display. For example, a program may maintain on the screen 
a list of values that change cyclically. When a number first changes, it 
can be displayed in reverse video to highlight it as a change on that cycle. 

On the next cycle, the same number must be displayed, but the reverse 
video should be removed, since the value of the number did not change. 
SMG$CHANGE_RENDITION provides an easy way to perform such 
changes. 

Another use for the SMG$CHANGE_RENDITION routine is in implementing 
menus. Menu choices can be painted on the screen and the current choice 
highlighted by some video rendition. As the user moves a cursor to change 
his or her selection, the renditions of menu items can be altered so that the 
current selection is always highlighted. Such changes in rendition can be 
made independently of the text that is contained in the menu choices. 

To specify the default rendition for a virtual display, you use bit masks to set 
bits in the display-attributes argument. The following bits can be set: 


SMG$M_BLINK 

SMG$M_BOLD 

SMG$M_REVERSE 

SMG$M_UNDERLINE 


Specifies blinking characters 

Specifies characters in higher-than-normal intensity 

Specifies characters in reverse video, that is, the 
opposite of the current default rendition of the 
virtual display 

Specifies underlined characters 


Any or all of these masks can be specified in the default rendition of a virtual 
display. To specify more than one video attribute, you use the logical OR 
of these masks. For example, to specify underlined characters in reverse 
video as the default for a virtual display, you assign the logical OR of the 
appropriate bit masks to the display-attributes argument: 

Display.attributes = ( SMG$M_REVERSE OR SMG$M_UNDERLINE ) 

You then pass this display-attributes argument in the call to the 
SMG$CREATE_VIRTUAL_DISPLAY procedure. 

Screen management output procedures let you override the default rendition 
so that you need not change the default each time you want to write text 
in some other rendition. Two arguments provide the means to override the 
default rendition: rendition-set and rendition-complement. The scheme for 
setting video attributes in these arguments is the same as that for setting the 
default video attributes when creating a virtual display. 
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The default video attributes, the rendition-set argument, and the rendition- 
complement argument together specify the output rendition according to the 
following scheme: 

• The logical or bitwise OR operation is performed on the mask containing 
the default video attributes and the rendition-set argument. 

• The logical or bitwise EXCLUSIVE OR operation is performed on the 
result of the previous OR operation and the rendition-complement 
argument. 

The results of this scheme are shown in the following table. 


Set 

Complement 

Action 

0 

0 

Attribute unchanged 

1 

0 

Attribute on 

0 

1 

Attribute set to complement of default setting 

1 

1 

Attribute off 


Note that the effect of this scheme depends on the default rendition, not 
the current rendition of the virtual display. Thus, if you have used screen 
management output routines that explicitly specify a rendition, the current 
rendition may not match the default rendition for that virtual display. 


3.4.7 Drawing Lines 

Two procedures provide a simple way to construct horizontal and vertical 
lines. SMG$DRAW_LINE constructs either horizontal or vertical lines, 
given the end points of those lines. SMG$DRAW_RECTANGLE draws a 
rectangular box given two diagonal vertices. 

Like all screen management procedures, these two are device independent. 

If the resulting line is to be drawn on a VT100, the VT100 line-drawing 
character set is used. If the same line is drawn on a VT52 (which does not 
have this hardware capability), the lines will automatically be approximated 
by the use of the plus sign ( + ), the vertical bar (I), and the dash (-). Your 
program does not have to supply different character codes for different types 
of terminals. 

In addition, these procedures automatically provide an appropriate character 
at the intersection of two lines. For example, if a program writes a horizontal 
line directly to the screen and then writes a vertical line that intersects the 
horizontal line, you normally would see this: 


ZK-1916-84 
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If these same lines are drawn using SMG$DRAW_LINE, the screen shows 
this: 


+ 


I 

i 


ZK-1917-84 


3.4.8 Reading Back from Virtual Display 

The SMG$READ_FROM_DISPLAY procedure is provided to make it easy 
to obtain text from a virtual display. This procedure might be used in 
applications that present menu items on the screen by way of a virtual 
display. The application might allow the user to move the cursor among the 
menu items and then select one (by pressing RETURN, for example). At this 
point, the program can read characters back from the display at the current 
cursor position and determine which menu item was selected. 


3.5 Input Through Virtual Keyboards 

This section describes the SMG procedures used to perform input from 
a virtual keyboard. Remember that while a virtual keyboard is usually 
associated with a terminal, it may also be associated with any RMS file. 

The Screen Management Facility provides a flexible set of procedures for 
performing input from a terminal or a file. The input procedures can be 
used in conjunction with the output procedures, or they can be used by 
themselves. You establish an input source, called a virtual keyboard, by 
calling the SMG$CREATE_VIRTUAL_KEYBOARD procedure. You delete 
a virtual keyboard by calling the SMG$DELETE_VIRTUAL_KEYBOARD 
procedure. 

Data may be obtained from a virtual keyboard in two ways. SMG$READ_ 
STRING reads a string composed of characters and a terminator; this 
procedure is general purpose and flexible, providing access to many features 
of the VAX/VMS terminal driver. SMG$READ_COMPOSED_LINE reads a 
line composed of ordinary keystrokes and predefined strings associated with 
keypad and control keys; it provides an easy way to code an interface for 
command-oriented utilities by providing single-key command capabilities. 
(SMG$READ_KEYSTROKE and SMG$READ_VERIFY may also be used.) 
Both types of read operations can be cancelled before completion by calling 
the SMG$CANCEU_INPUT procedure. 
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3.5.1 Terminators 


A terminator ends a transfer of data from the virtual keyboard. A terminator 
may be a single character such as carriage return or CTRL/Z, a character 
sequence (escape sequence) generated by pressing a function key on a 
keyboard, or a condition such as timeout or buffer full. 

The terminator is not part of the data read from the virtual keyboard; it is 
returned to the caller of SMG$READ_STRING, SMG$READ-KEYSTROKE, 
and SMG$READ_VERIFY in a separate argument as an integer (unsigned 
word) code value. For single-character terminators, the code value is the 
terminator's 8-bit character code. Single-character terminator codes are in the 
range 0 through 255. 

Character sequence terminators are returned in a device-independent fashion, 
using code numbers in the range 256 through 495. A unique code is assigned 
to each possible function key on VT220 (and VT200-compatible) terminals. 
Key codes on other terminals are returned using the code of the equivalent 
VT220 key. Therefore, the application program need not know which type of 
terminal is being used; the screen management procedures transparently map 
the different terminator character sequences into a uniform set of function 
codes. 

Input operations terminated by a condition are indicated by terminator 
codes in the range 496 through 511. If the input is from an RMS file, 
each input operation reads one record from the file; the terminator code is 
always the code for a RETURN. (The only exception to this is SMG$READ_ 
KEYSTROKE, in which the terminator code is the first character in the 
record.) 

For calls to SMG$READ_STRING and SMG$READ_VERIFY, the default 
single terminator characters are all characters in the range 0 through 31 
except backspace (8), horizontal tab (9), line feed (10), vertical tab (11), and 
form feed (12). Note that these characters make up the default terminator 
set for the VAX/VMS terminal driver. However, any 8-bit character code is 
potentially a terminator. The set of terminator characters may be changed 
by calls to SMG$READ_STRING or SMG$READ_VERIFY. For calls to 
SMG$READ_COMPOSED_LINE, the default single terminator characters are 
only the carriage return (13) and CTRL/Z (26). Changes to the terminator set 
for SMG$READ_COMPOSED_LINE are made by key definitions; see the 
description of line composition in Section 3.5.2 for more information. 

Table 3-1 lists the terminator name or condition for each terminator that 
is not a single character. The table also lists the code number and the key 
legend for each terminator on the different types of terminals supported by 
the screen management input procedures. 


Family Terminals Included 

VT220 VT2xx, Professional 3xx in "Pro" mode 

VTIOO VTIxx, LA 120, LA34, LA38, LA 12, (Professional 3xx, Rainbow 100, 
and DECmate II in VT102 or VT125 modes) 

VT52 VT52, VT55, VT61, VT220 in VT52 mode, VT100 in VT52 mode 
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Table 3-1 Terminator Codes 


Key Name 

Code 

VT200 series 

VT100 

VT52 

Keypad Keys 





DELETE 

127 

<- 

DELETE 

DEL 

PF1 

256 

PF1 

PF1 

Blue 

PF2 

257 

PF2 

PF2 

Red 

PF3 

258 

PF3 

PF3 

Black 

PF4 

259 

PF4 

PF4 


KPO 1 

260 

0 

0 

0 

KP1 1 

261 

1 

1 

1 

KP2 1 

262 

2 

2 

2 

KP3 1 

263 

3 

3 

3 

KP4 1 

264 

4 

4 

4 

KP5 1 

265 

5 

5 

5 

KP6 1 

266 

6 

6 

6 

KP7 1 

267 

7 

7 

7 

KP8 1 

268 

8 

8 

8 

KP9 1 

269 

9 

9 

9 

ENTER 2 

270 

ENTER 

ENTER 

ENTER 

MINUS 1 

271 

- 

- 


COMMA 1 

272 

, 

, 


PERIOD 1 

273 




Cursor Positioning Keys 




UP 

274 

Up arrow 

Up arrow 

Up arrow 

DOWN 

275 

Down arrow 

Down arrow 

Down arrow 

LEFT 

276 

Left arrow 

Left arrow 

Left arrow 

RIGHT 

277 

Right arrow 

Right arrow 

Right arrow 

Function Keys 





F6 

286 

F6 



F7 

287 

F7 



F8 

288 

F8 



F9 

289 

F9 



F10 

290 

F10 



F11 

291 

F11 



F12 

292 

F12 




1 These are the keys on the numeric keypad, not the main keyboard. These codes 
are used only if the terminal keypad is in applications mode; if the keypad is in 
numeric mode, the keys are equivalent to the keys with the same legends on 
the main keyboard. See the description of SMG$SET_KEYPAD_MODE for more 
information. 

2 lf the keypad is in numeric mode, ENTER is equivalent to a carriage return. See 
the description of SMG$SET_KEYPAD_MODE for more information. 
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Table 3-1 (Cent.) Terminator Codes 


Key Name Code VT200 series VT100 VT52 


F13 

293 

F13 

F14 

294 

F14 

HELP 3 

295 

HELP 

CO 

O 

O 

296 

DO 

F1 7 

297 

F17 

F18 

298 

F18 

F19 

299 

F19 

F20 

300 

F20 

Editing Keys 



FIND 

311 

Find 

INSERT_HERE 

312 

Insert Here 

REMOVE 

313 

Remove 

SELECT 

314 

Select 

PREV_SCREEN 

315 

Prev Screen 

NEXT_SCREEN 

316 

Next Screen 

Conditions 



CANCELLED 

508 


TIMEOUT 

509 


BUFFER_FULL 

510 


UNKNOWN 4 

51 1 



3 HELP and DO are in the FI5 and FI6 positions on the VT220 keyboard. 

4 lf an unrecognized terminator sequence is received, the terminator code is 511. 


Symbolic definitions of the terminator codes are provided in DIGITAL- 
supplied symbol libraries named SMGDEF (for example, in a MACRO 
program you would issue a $SMGDEF to extract these definitions). The 
symbol names are of the form SMG$K_TRM_keyname, where keyname 
is the key name given in Table 3-1. For terminator codes 1 through 26, 
which correspond to the characters CTRL/A through CTRL/Z, the key names 
are CTRLA for CTRL/A, CTRLB for CTRL/B, and so on. The following 
synonyms are also defined: 
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Symbol 

Synonym 

SMG$K_TRM_BS 

SMG$K_TRM_CTRLH 

SMG$K_TRM_HT 

SMG$K_TRM_CTRLI 

SMG$K_TRM_LF 

SMG$K_TRM_CTRLJ 

SMG$K_TRM_CR 

SMG$K_TRM_CTRLM 

SMG$K_TRM_E1 

SMG$K_TRM_FIND 

SMG$K_TRM_E2 

SMG$K_TRM_INSERT_HERE 

SMG$K_TRM_E3 

SMG$K_TRM—REMOVE 

SMG$K_TRM_E4 

SMG$K_TRM—SELECT 

SMG$K_TRM_E5 

SMG$K—TRM—PREV—SCREEN 

SMG$K_TRM_E6 

SMG$K_TRM—NEXTSCREEN 

SMG$K_TRM_F 15 

HELP 

SMG$K_TRM_F 16 

DO 


3.5.2 Line Composition Using Keypad Keys 

In addition to the functions provided by SMG$READ_STRING, line 
composition with keypad keys provides a powerful and flexible tool for 
applications that have line-oriented commands (for example, utilities that use 
the Command Definition Utility). (See the VAX/VMS Command Definition 
Utility Reference Manual for more information on the Command Definition 
Utility.) 

With line composition, you can define certain keys (discussed below) to 
be equivalent to a string of characters. When you enter a line and press 
one of these keys, the equivalence string for that key is inserted into the 
returned command string. For example, if the application defines the key 
PF2 to have the equivalence string "HELP", then when you press the PF2 
key, that command is returned to the application. You can also specify that 
the equivalence string is echoed; in this case, the string "HELP" is echoed. 
The recognition of keypad keys and the insertion of the equivalence string is 
handled automatically by SMG$READ_COMPOSED_LINE; the application 
treats the returned line just as if you had typed the entire line. 

Key definitions are placed in a key definition table, which is created by 
a call to SMG$CREATE_KEY_TABLE. Key definitions can be added and 
deleted from the table by calls to SMG$ADD_KEY_DEF and SMG$DELETE_ 
KEY—DEF. Key definitions can also be added by calls to SMG$DEFINE_ 

KEY and SMG$LOAD_KEY_DEFS; these procedures accept a DCL DEFINE 
/KEY command (or a file of these commands). See the description of these 
procedures for more information; see the VAX/VMS DCL Dictionary for an 
explanation of the DEFINE/KEY command. 

The keys that can be defined are function and keypad keys listed in Table 3-1 
with terminator codes in the range 256 through 496, plus the control keys 
(CTRLA through CTRLZ) with the exception of CTRLM (RETURN). 

A key definition has several attributes. The TERMINATE attribute specifies 
whether the input line is terminated when this key is pressed; the 
NOTERMINATE attribute specifies that more characters and keystrokes 
may be entered. TERMINATE is the default. 

The ECHO attribute specifies whether the equivalence string is echoed when 
the key is pressed. ECHO is the default. 
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The PROTECT attribute specifies whether this key definition can be changed 
or deleted once it is defined. NOPROTECT is the default. 

The remaining attributes are LOCK—STATE, IF—STATE, and STATE. They are 
described in Section 3.5.3. 


3.5.3 States 


A given key name may have many definitions, depending on the value of 
the current state; the state is used to qualify the meaning of the key. For 
example, if PF1 is defined as setting the state to "GOLD" and if PF2 with 
IF_STATE="GOLD" is defined as "HELP pressing PF1 and then PF2 would 
result in "HELP *" being returned as the command line. (Note that in this 
case, the PF1 definition would have no equivalence string and would specify 
the NOTERMINATE attribute.) 

A state name is any string comprised of 0 through 31 alphanumeric 
characters, including dollar sign ($) and underscore (_). When a line is being 
composed from normal keystrokes and equivalence strings, SMG$READ_ 
COMPOSED—LINE maintains a string called the current state name. Before 
the first key is pressed, the current state is the null string. If you press a key 
whose definition has specified a value for the STATE attribute, the current 
state is changed to the value of the STATE attribute. Unless specified by the 
LOCK—STATE attribute, the state name reverts to the null string after the 
next defined key is pressed. 


3.5.4 Interaction of Input and Output 

SMG$READ_COMPOSED_LINE, SMG$READ_KEYSTROKE, SMG$READ_ 
STRING, and SMG$READ_VERIFY accept an optional display-id argument. 
If a display-id is supplied, it designates the virtual display in which the input 
operation should occur. By specifying the display-id, you enable the Screen 
Management Facility to remain aware of the changes caused by character 
echoing. If you omit the display-id, the Screen Management Facility assumes 
that screen management output is not being used. 

Note that if the display-id argument is specified for any one of the above- 
mentioned input routines, then the length of the prompt-string plus the input 
is limited to the number of columns in the display or, where specified, to the 
maximum number of characters to be read. (In the case of SMG$READ_ 
KEYSTROKE, this restriction applies only to the length of the prompt-string.) 


3.6 Operational Controls 

This section describes the screen management procedures that control special 
modes of operation: minimal update, buffering, and whether or not tabs 
are used in updating. These modes let you optimize the manner in which 
information is actually written to the screen. To invoke these modes, you use 
the SMG$CONTROL —MODE procedure. 

Normally, you need not be concerned with these modes; the Screen 
Management Facility optimizes output so that characters appear to be 
displayed on the screen immediately. For some applications, however, you 
may want to take advantage of these mode settings. The following sections 
describe these modes of operation. 
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3.6.1 Minimal Update 

By default, the Screen Management Facility attempts to minimize the number 
of characters written to the screen by rewriting only the parts of the screen 
that have changed. However, the Screen Management Facility also supports 
nonminimal updating, in which all lines affected by a change are redrawn, 
beginning at the first changed character and continuing to the end of the line. 


3.6.2 Buffering 

By default, output operations cause an immediate change on the screen by 
sending many small, partially-filled buffers to the terminal instead of updating 
the screen when the buffer is full. Minimizing these I/O transactions by 
enabling buffering mode results in faster program execution. 

In buffering mode, the Screen Management Facility writes the terminal buffer 
to the screen only when the buffer is full. Thus, several output operations 
may be performed before the results appear on the screen. Because this delay 
is not acceptable for many applications, a special procedure, SMG$FLUSH_ 
BUFFER, is provided for use with buffering. SMG$FLUSH—BUFFER forces 
the buffer to be written to the terminal regardless of whether it is full. This 
procedure is useful for an application that can usually accept delayed output 
but occasionally requires an immediate screen update. Applications that 
usually need immediate changes on the screen should not enable buffering. 


3.6.3 Tabs 


Tabs are used for minimal updating. When you are using tabs, you must 
ensure that the tab stops are set to the DIGITAL default locations. Do not use 
tabs if you want to be sure that the application will run regardless of the tab 
settings the user has set on the terminal. 

Any tabs that you output to the screen are converted to eight spaces by SMG$ 
before being output to the screen. The only exception to this is seen in using 
SMG$CREATE—VIRTUAL—DISPLAY with the display-attributes argument 
set to SMG$K_DISPLAY—CONTROLS. In this case only, the tab character is 
printed rather than interpreted as eight spaces. 


3.7 Batching Output Operations 

If you want to construct a complex virtual display that requires several 
scrolling, cursor positioning, and output operations, but do not want the 
interim steps to be visible, you can batch the output operations. Batching a 
series of operations to a virtual display lets the application hide the interim 
steps. 

You may also want to construct a complex pasteboard image, but have it 
appear on the screen only after the entire picture is complete. Unpasting and 
repasting leaves the screen blank during the construction process, so in this 
case you can batch a series of composition operations and let the screen show 
only the final effect. 

The Screen Management Facility provides a mechanism for batching a 
series of operations at both the virtual display level (see Section 3.7.1) and 
pasteboard level (see Section 3.7.2). 
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3.7.1 Display Update Batching 

The SMG$BEGIN_DISPLAY_UPDATE procedure causes output operations 
to a pasted display to be reflected only in the display's buffers. When 
all operations to the display are finished, the application can call the 
SMG$END_DISPLAY—UPDATE procedure, which causes the display's buffer 
to be written to the pasteboard. 

The SMG$BEGIN_DISPLAY_UPDATE and SMG$END_DISPLAY_UPDATE 
routines increment and decrement a counter. When this counter's value is 
zero, output to the virtual display is immediately sent to the pasteboard. 
When the counter's value is nonzero, output operations are batched; the 
display batching level is equal to the counter's value. Notice that the counter 
mechanism allows a subroutine to request and turn off batching without 
disturbing the batching level of the calling program. 


3.7.2 Pasteboard Update Batching 

You begin pasteboard batching by calling the SMG$BEGIN—PASTEBOARD- 
UPDATE procedure, performing several composition operations, and 
finally calling the SMG$END_PASTEBOARD—UPDATE procedure. The 
SMG$BEGIN_PASTEBOARD—UPDATE procedure causes output operations 
to be reflected only in the pasteboard buffer, not on the physical screen. The 
SMG$END_PASTEBOARD—UPDATE procedure causes the pasteboard buffer 
to be written to the physical screen. 

The SMG$BEGIN —PASTEBOARD—UPDATE and SMG$END_ 
PASTEBOARD—UPDATE routines increment and decrement a counter. When 
this counter's value is zero, output to the pasteboard is immediately sent to 
the physical screen. When the counter's value is nonzero, output operations 
are batched; the pasteboard batching level is equal to the value of the counter. 
Notice that the counter mechanism allows a subroutine to request and turn 
off batching without disturbing the batching level of the calling program. 


3.8 Advanced Features 

The Screen Management Facility provides several advanced features that let 
you control the following: 

• Asynchronous events and actions 

• Output to a file or hardcopy device 

• Physical cursor positioning 

The following sections describe these features. 
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3.8.1 Control of Asynchronous Events 

There are three types of asynchronous events that can disrupt the screen 
image. 

• Broadcast messages 

• Unsolicited input 

• Out-of-band asynchronous system traps 

The following sections explain how to control these actions. 


3.8.1.1 Broadcast Messages 

Normally, broadcast messages (for example, MAIL notifications or operator 
messages) can appear on the terminal screen at any time, destroying or 
distorting the screen image. The SMG$SET_BROADCAST_TRAPPING 
procedure lets you trap messages broadcast to the specified terminal 
(pasteboard) and in addition, lets you specify an AST routine to be called 
whenever a broadcast message is trapped. The AST routine you supply 
can access the broadcast message by calling the SMG$GET_BROADCAST— 
MESSAGE procedure. 

Whether or not you specify an AST routine in the call to SMG$SET_ 
BROADCAST-TRAPPING, you can check for the receipt of a broadcast 
message at any time by calling SMG$GET_BROADCAST-MESSAGE. 


3.8.1.2 Unsolicited Input 

The SMG$ENABLE_UNSOLICITED—INPUT procedure detects the presence 
of unsolicited input. Note that this routine does not read any input characters; 
it merely calls an AST routine to notify the application that it should issue 
a read operation with SMG$READ_COMPOSED—LINE, SMG$READ_ 
KEYSTROKE, SMG$READ_STRING or SMG$READ_VERIFY. It is up to you 
to read the unsolicited input. 


3.8.1.3 Out-of-Band ASTs 

The SMG$SET_OUT—OF_BAND—ASTS procedure provides a way to trap 
out-of-band characters such as CTRL/Y, CTRL/C, and CTRL/O. This 
procedure lets you specify which characters are to be treated as out-of- 
band characters and also lets you specify an AST routine to be called when 
one of these characters is typed. 


3.8.2 Snapshots 

If the output device for screen management procedures is a file or a hardcopy 
terminal, the output for screen updating is inappropriate for the device. The 
SMG$SNAPSHOT procedure lets you send the current screen image, that 
is, the visible portion of the pasteboard, to the file or hardcopy terminal. 
Pasteboard batching does not affect the SMG$SNAPSHOT procedure. 


3.8.3 Special Procedures 

The Screen Management facility provides the special procedure of moving 
the cursor to a specified location on the physical screen. It does so through 
the SMG$SET_PHYSICAL—CURSOR procedure. However, if you attempt to 
move the cursor to a pasteboard position outside the screen boundaries, an 
error is returned. 
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.9 Using Screen Management Procedures to Develop New 
Programs 

This section discusses some recommended methods for using the Screen 
Management Facility for developing new programs. It is important to note 
that Screen Management procedures are not AST reentrant. 

There are two ways in which an application can call Screen Management 
procedures. 

• Directly 

Applications that call the Screen Management Facility directly already use 
pasteboards and virtual displays. 

• Indirectly 

This kind of application does not use the Screen Management Facility 
directly, but may use it in the course of invoking other routines. 

As time goes on, and more and more callable procedures may use the 
Screen Management Facility to produce their output, it becomes more 
difficult to determine whether your application is in this category. 

In either case, the calling procedure is likely at some point to call a subsystem 
so that the subsystem can write data to the screen. 

At some later point, the terminal user will want to remove the subsystem- 
specific display. However, if the subsystem created and used a virtual display 
to display the data, the display-id is not available to the calling program 
and therefore the calling program cannot remove it. Furthermore, unless 
the calling program is a direct user of the Screen Management Facility, the 
screen's pasteboard-id is also not available to it. 

The solution is to require that all callable procedures that use the Screen 
Management Facility, directly or indirectly, have an (optional) input 
argument for the pasteboard-id and an (optional) output argument for 
the virtual display-id. Passing the pasteboard and display-ids lets you avoid 
accumulating subsystem-specific data on the screen which cannot be removed 
by the calling program. These guidelines are developed below. 

• If the pasteboard-id argument is provided by the calling program, then: 

1 The called program should not create a pasteboard of its own. 

2 The called program must deliver all of its output to the pasteboard 
supplied by the calling program; that is, the called program may paste 
its displays only to the pasteboard specified by the pasteboard-id. 

3 The called program may delete any virtual displays it created by 
calling SMG$DELETE-VIRTUAL-DISPLAY, but it must not delete 
the pasteboard. 

Note that the called program should not simply call the 
SMG$UNPASTE_VIRTUAL—DISPLAY procedure with the expectation 
that this virtual display can be reused on a later invocation. Since the 
called program and the calling program are sharing a pasteboard, 
the calling program may use the SMG$POP_VIRTUAL— DISPLAY 
procedure to delete all displays created by the called program. 

4 The called program must pass the pasteboard-id on to any procedures 
it in turn calls. Thus all output is directed to the specified pasteboard. 
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• If the pasteboard-id argument is not provided by the calling program, 
then: 

1 The called program must create a pasteboard on its own. The called 
program may allocate any physical device for the pasteboard, unless 
specifically directed to a particular device by some other mechanism. 

The called program must check the status of the SMG$CREATE_ 
PASTEBOARD call to see whether it created a unique pasteboard- 
id or whether it received the pasteboard-id of an already existing 
pasteboard. If the pasteboard already exists, the called program must 
not delete the pasteboard. 

2 If the called procedure creates a pasteboard and it in turn calls 
subroutines that may use pasteboards, it should pass the pasteboard-id 
to the subroutine. 

3 The called program may clean up by using the SMG$UNPASTE_ 
VIRTUAL—DISPLAY procedure, and the displays can be saved for 
reuse on a subsequent invocation if such a call seems likely. Note, 
however, that the SMG$UNPASTE_VIRTUAL— DISPLAY procedure 
should be used only if the called program creates its own pasteboard, 
because in this case the calling program cannot delete the virtual 
displays created by the called program. 

• If the virtual display-id argument is provided by the calling program, 
then the calling program must clean up any virtual displays created by the 
called program. The called program must return to the calling program the 
id of the first virtual display pasted. The calling program can then remove 
this and all higher-pasted virtual displays by calling the SMG$POP_ 
VIRTUAL-DISPLAY procedure. 

• If the virtual display-id argument is not provided by the calling program, 
the called program must remove all the virtual displays it pasted to the 
pasteboard. 

By following these guidelines, you can develop your application in a modular 

fashion. 

• Calling programs control the pasteboard on which information is pasted. 
Pasteboard-ids flow downward in a hierarchy, with each routine using the 
pasteboard-id provided by the caller and passing it along to subroutines. 

• If a calling program supplies a virtual display-id argument to be filled in 
by the called program, then the calling program assumes responsibility 
for cleaning up any displays created by the called program. The called 
program passes back the display-id of the first virtual display pasted so 
that the calling program can remove this and all higher-pasted displays by 
calling the SMG$POP_VIRTUAL-DISPLAY procedure. 

• Virtual displays are created (and pasted) in the procedure where they are 
needed. If the calling program does not supply a display-id argument, 
then displays are unpasted and/or deleted in the procedure that created 
them. 
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3.9.1 Calling Routines That Do Not Use the Screen Management Facility 

A different situation exists if you call a subroutine (or subsystem) that writes 
to the screen without using the Screen Management Facility. When the 
Screen Management Facility is bypassed (that is, when text is placed on the 
screen outside of screen management's control), problems result when an 
attempt is made to perform a screen update. 

For this reason, the Screen Management Facility provides two procedures for 
turning over the screen (or a part of it) temporarily to a program that does 
not use screen management, and for restoring the screen to its previous state 
after control is returned from the non-SMG$ procedure. These procedures 
are SMG$SAVE—PHYSICAL —SCREEN and SMG$RESTORE—PHYSICAL — 
SCREEN. 

Before you call a procedure that performs non-SMG$ I/O to the screen, you 
should call the SMG$SAVE-PHYSICAL-SCREEN procedure, specifying 
what part of the screen is to be turned over to the non-SMG$ procedure. 
SMG$SAVE_PHYSICAL—SCREEN erases the specified area, sets the 
terminal's physical scrolling region to this area, and sets the physical cursor 
to row 1, column 1 of the area. If the non-SMG$ code does only sequential 
input and output (that is, if it does no direct cursor addressing) its output will 
be confined to the specified area of the screen. 

When control is returned from the non-SMG$ procedure, you simply call 
SMG$RESTORE_PHYSICAL—SCREEN, which restores the screen image as 
it was before the call to SMG$SAVE-PHYSICAL-SCREEN. 


3.9.2 Writing Exit Handlers 

The Screen Management Facility supplies an exit handler, which is invoked 
before image termination. This handler deletes all pasteboards and virtual 
keyboards associated with the current image and resets the terminal 
characteristics. The Screen Management Facility also allows you to supply 
your own exit handler, in which you can perform any other tasks required 
before exiting the image. The Screen Management Facility's exit handler 
may or may not be invoked before the user-supplied exit handler. Therefore, 
you should not delete pasteboards or virtual displays from inside a user- 
supplied exit handler since they may have already been deleted by the Screen 
Management Facility exit handler and their identifiers deassigned. 
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3.10 Support for Non-DIGITAL Terminals 

This section describes a new method of supporting foreign (non-DIGITAL) 
terminals. This method is used by the Screen Management Facility but it 
can also be used by application programs that need to do their own I/O to 
foreign terminals. Thus, if you use the Screen Management Facility, you need 
to concern yourself only with the definition of foreign terminal capabilities, 
and not with the details of calling the foreign terminal routines directly. 
Further, you need to define only a few terminal capabilities ("set absolute 
cursor position," "erase to end of display," and "erase to end of line") in 
order for the Screen Management Facility to effectively control the terminal 
screen. However, the routines used by the Screen Management Facility are 
documented here in case you decide to do your own I/O to foreign terminals. 

The new method of support begins with a source file named 
TERMTABLE.TXT, which contains a list of terminal names and their 
associated capabilities. This file is processed by the SMGBLDTRM program to 
create an image file called TERMTABLE.EXE. The following sections describe 
the creation and processing of the TERMTABLE database. 

Note that the TERMTABLE support is used by the Screen Management 
Facility for all terminals, including DIGITAL terminals. The definitions for 
DIGITAL terminals are included in a file named SMGTERMS.TXT, which is 
provided as part of the Screen Management Facility. The examples in the 
following section show you how to use the Foreign Terminal package to 
define DIGITAL terminals, because most users are familiar with them. Note 
that you should not create your own definitions for DIGITAL terminals, nor 
should you modify the definitions in SMGTERMS.TXT. 


3.10.1 Creating a VMS Terminal Capabilities File 

The source code for the database is an ASCII file named TERMTABLE.TXT. 
This file contains an entry for each type of terminal. Each entry lists 
a terminal's capabilities and other device-specific information, such as 
initialization sequences and screen size; a TERMTABLE entry can span more 
than one record in the file. A terminal definition can be added by editing 
the TERMTABLE.TXT file; TERMTABLE.TXT must then be reprocessed by 
running SYS$SYSTEM:SMGBLDTRM.EXE. 

TERMTABLE.TXT can be created with any text editor. A TERMTABLE entry 
consists of a terminal name, followed by any number of capability fields and 
their values (see Section 3.10.2 for more information about capability fields). 
Although TERMTABLE.TXT must be formatted for compilation, capability 
names are descriptive and can be easily understood by a human being. 
Terminal names must be unique; for example, if more than one definition 
is needed for a Hazeltine terminal, then a second name, Hazeltine_2, for 
instance, must be invented. 

When a TERMTABLE routine first searches for a terminal entry, it tries to 
find TERMTABLE.EXE in the area logically named TERM$TABLOC. If the 
specified terminal entry is not found there, the routine then searches for 
TERMTABLE.EXE in SYS$SYSTEM. If you want to use a terminal definition 
that differs from the system definition for that terminal, you can create a 
private copy of TERMTABLE.TXT and TERMTABLE.EXE. You can then 
define a single terminal with a definition that is different from the one in 
SYS$SYSTEM:TERMTABLE.EXE and still use the rest of the standard system 
definitions. 
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The format of a TERMTABLE entry is as follows: 

NAME = "terminal-name" 
capability-tield [,...] 

END 

Note that the TERMTABLE.TXT file allows you to include REQUIRE 
directives. The REQUIRE directive lets you include separate source files in 
the TERMTABLE.TXT file. Its format is as follows: 

REQUIRE "file-spec" 

In the above format, "file-spec" is a valid VAX/VMS file specification. 

The following sections describe the format of capability fields. 


3.10.2 Capability Fields 

Three types of capability fields are allowed in a TERMTABLE entry. 

• Boolean 

• Numeric 

• String 

The following sections describe these capabililty fields in detail. Note that 
some of the capability fields described in these sections have a corresponding 
UNIX 1 name, which appears in parentheses next to the VMS name. The 
UNIX 1 name is included only as an aid for conversion. Note that the case of 
the letters in the UNIX 1 name is significant. 

Functions that are common to most terminals have been chosen as possible 
fields; not all functions of all terminal types are represented. (Specifically, 
there is no support for block mode, graphics, or typesetting composition 
functions.) Screen-oriented applications should be planned around typical 
terminal functions, and not depend on features that exist on only one or a 
few models. 

For applications that must support an unusual terminal, some generic 
capability names are reserved for user definition. Names of the form 
PRIVATE_STR_n, PRIVATE_BOO_n, and PRIVATE_NUM_n, where n is 
a number from 1 to 10, may be included as user-defined terminal definitions 
and returned by the TERMTABLE interface routines. Since meanings are 
assigned by the user, private capabilities will vary between applications. Sites 
running several applications must guard against multiple definitions for a 
single private capability. (For example, you should include separate terminal 
entries for a terminal that requires PRIVATE_STR_1 to mean two different 
things, depending on the application program being run.) In general, it 
should not be necessary to resort to private capabilities. 

The following characters are used as delimiters in capability fields. 


Delimiter 

Meaning 

! 

Begins a comment 

= 

Separates a capability field name from its value 

, 

Separates capability fields 


Delimits strings 


1 UNIX is a trademark of Bell Laboratories. 
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3 . 10 . 2.1 


Boolean Capability Fields 

Boolean capabilities are either present, or not present, for a given terminal. 
The format for a Boolean capability field is as follows: 

BOOLEAN 

{boolean-capability = binary-digit} [,...] 

Where: 

boolean-capability Is one of the capability fields listed in 

Table 3-2. 

binary-digit Is either a 1 or a 0. 

Table 3-2 lists these Boolean capability fields. 


Table 3-2 Boolean Capabilities 


VMS Name 

Used 

by 

SMG 

Description 

ADVANCED_VIDEO 

N 

If set, the terminal has advanced 
video attributes and is capable of 
132-column mode operation 

ANSI-CRT 

N 

If set, terminal conforms to ANSI 
CRT programming standards 

AUTO_MARGIN (am) 

N 

If set, terminal has automatic 
margins 

BACKSPACE (bs) 

Y 

If set, terminal can backspace with 
CTRL/H 

BLOCK-MODE 

N 

If set, terminal can perform block 
mode transmission, local editing, 
and field protection 

CURSOR_REPORT_ANSI 

N 

If set, terminal uses the ANSI 
sequence to report the current 
cursor location 

DEC—CRT 

Y 

If set, terminal conforms to 
DIGITAL VT 100-family standards 

DEC—CRT—2 

N 

If set, terminal conforms to 
DIGITAL VT200-family standards 

EDIT 

N 

If set, terminal can perform ANSI- 
defined advanced editing functions 

EIGHT-BIT 

N 

If set, terminal uses 8-bit ASCII 
character code 

FULLDUP 

N 

If set, terminal operation mode is 
full-duplex (half-duplex if not set) 

IGNORE—NEWLINE (xn) 

N 

If set, terminal ignores a newline 
after a wrap 

INSERT_MODE_NULLS (in) 

N 

If set, insert mode distinguishes 
nulls on display 

LOWERCASE 

N 

If set, terminal has both uppercase 
and lowercase letters 
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Table 3-2 (Cont.) Boolean Capabilities 


VMS Name 

Used 

by 

SMG 

Description 

NO—ERASE (xs) 

N 

If set, standout (bolded) characters 
are not erased by writing over 
them 

NO—SCROLL (ns) 

N 

If set, terminal is not capable of 
scrolling 

OVERSTRIKE (os) 

N 

If set, terminal is capable of 
overstriking 

PHYSICALFF 

N 

If set, terminal can accept form 
feeds (If not set, terminal driver 
must translate form feeds to 
multiple line feeds) 

PHYSICAI_TABS (pt) 

N 

If set, terminal has hardware tabs 
(Note that these tabs may need to 
be set with an initialization string) 

PRINTER_PORT 

N 

If set, terminal has a printer port 
available 

PRIV ATE—BOO— 1 to 10 

N 

If set, these fields denote user- 
defined capabilities 1 through 

10 

REGIS 

N 

If set, terminal understands Regis 
graphics commands 

SCOPE 

Y 

If set, terminal is a video terminal 

SIXELGRAPHICS 

N 

If set, terminal can display 
graphics using the REGIS-defined 
SIXEL graphics protocol 

SOFT_CHARACTERS 

N 

If set, terminal can load a user- 
defined character set 

UNDERLINE (ul) 

N 

If set, terminal has underlining 
capability (but not overstrike) 


For example, the following TERMTABLE entry describes two characteristics of 
a VT100 terminal: 

NAME = "VT100" 

BOOLEAN 

ansi_crt = 1, dec.crt = 1 

This entry specifies that the terminal conforms to ANSI CRT programming 
standards and to DIGITAL VTlOO-family standards. 
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3 . 10 . 2.2 


Numeric Capability Fields 

Numeric capababilities are those that take a numeric argument, for example, 
the number of columns on the terminal screen. 

The format for a numeric capability field is as follows: 

NUMERIC 

{numeric-capability * value} [,...] 

Where: 

numeric-capability Is one of the capability fields listed in 

Table 3-3. 

value Is the value for the specified numeric 

capability. 


Table 3-3 lists numeric capabilities. 


Table 3-3 Numeric Capabilities 


VMS Name 

Used by SMG 

Description 

COLUMNS (co) 

N 

Specifies the number of 
columns in a line 

CR—FILL (dC) 

N 

Specifies the number of fill 
characters needed after a 
RETURN 

LF_FILL (dF) 

N 

Specifies the number of fill 
characters needed after a line 
feed 

FRAME 

N 

Controls the number of data 
bits expected by the terminal 
driver for every character that 
is input or output (value must 
be between 5 and 8, inclusive) 

NUMBER_FN_KEYS 

N 

Specifies the number of 
function keys available 

PRIVATE_NUM_1 to 10 

N 

If set, these fields denote user- 
defined capabilities 1 through 

10 

ROWS (li) 

Y 

Specifies the number of rows 
on the screen 

WIDE_SCREEN_COLUMNS 

N 

Specifies the number of 
columns available in wide 
mode 


For example, the following TERMTABLE entry describes two characteristics of 
a VT100 terminal: 

NAME = "VT100" 

NUMERIC 

rows = 24, columns = 80 


3-31 







Screen Management Guidelines 

Support for Non-DIGITAL Terminals 


3.10.2.3 


String Capability Fields 

String capability fields provide several features. They let you: 

• Supply alternate characters for line-drawing 

• Provide icons so that your program can display carriage-control characters 
(for example, form feeds) rather than executing them 

• Supply the character sequences that cause a given operation (for example, 
ERASE_TO_END_LINE) to be performed on any number of different 
terminals 

• Specify the character strings returned by special keys (for example, 
function keys) on a given terminal 

Table 3-4 lists string capabilities. 


Table 3-4 String Capabilities 


Name 

Used by SMG 

Description 

BEGIN_ALTERNATE_CHAR (as) 

N 

Begins alternate character 
set 

BEGIN_AUTOPRINT_MODE 

N 

Begins autoprint mode 

BEGIN_AUTOREPEAT_MODE 

N 

Begins autorepeat mode 

BEGIN_AUTOWRAP_MODE 

N 

Begins autowrap mode 

BEGIN_BLINK 

Y 

Begins blinking characters 

BEGIN_BOLD (so) 

Y 

Begins bolded characters 
(standout mode) 

BEGIN_DELETE_MODE (dm) 

N 

Begins delete mode 

BEGIN_INSERT_MODE (im) 

N 

Begins insert mode 

BEGIN_LINE_DRAWING_CHAR 

Y 

Begins using line drawing 
character set 

BEGIN_NORMAI_RENDITION 

Y 

Begins using normal video 
attributes 

BEGIN_REVERSE 

Y 

Begins reverse video 
characters 

BEGIN_UNDERSCORE (us) 

Y 

Begins underscored 
characters 

BOTT OM_T_CH AR 

Y 

Displays line drawing 
character—bottom t 

CLEAR_TAB 

N 

Clears tab at current 
column 

CR_GRAPHIC 

Y 

Defines character to 
indicate a carriage return 
when control characters 
are being represented 
rather than executed 

CROSS_CHAR 

Y 

Defines character to 
represent the intersection 
of perpendicular lines 
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Table 3-4 (Cont.) String Capabilities 


Name 


Used by SMG Description 


CURSOR-DOWN (do) N 

CURSOR-LEFT N 

CURSOR_NEXT_LINE N 

CURSOR_POSITION_REPORT N 

CURSOR_PRECEDING_LINE N 

CURSOR-RIGHT (ch) N 

CURSOR-UP (up) N 

DARK_SCREEN Y 

DELETE_CHAR (dc) N 

DELETE_LINE (dl) N 

DEVICE-ATTRIBUTES N 

DOUBLE_HIGH_BOTTOM Y 

DOUBLE_HIGH_TOP Y 

DOUBLE-WIDE Y 

END_ALTERNATE_CHAR (ae) N 

END_AUTOPRINT_MODE N 

END_AUTOREPEAT_MODE N 

END_AUTOWRAP_MODE N 

END_BLINK N 

END-BOLD (se) N 


Moves cursor n lines 
down (will not cause 
scrolling) 

Moves cursor n positions 
to the left 

Accepts an argument n 
and moves the cursor to 
the first position in the 
nth following line 

Reports the active 
position via two 
arguments 

Accepts an argument n 
and moves the cursor to 
the first position in the 
nth preceding line 

Accepts an argument n 
and moves the cursor n 
positions to the right 

Accepts an argument n 
and and moves cursor up 
n lines (does not cause 
scrolling) 

Makes screen background 
color dark (normal video) 

Accepts an argument n 
and deletes n characters 

Accepts an argument n 
and deletes n lines 

Terminal's response 
to a "What are you?" 
sequence 

Changes line to double 
high bottom half 

Changes line to double 
high top half 

Changes line to double 
wide 

Ends alternate character 
set 

Ends autoprint mode 
Ends autorepeat mode 
Ends autowrap mode 
Ends blinking characters 

Ends bold (stand out) 
mode 
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Table 3-4 (Cont.) String Capabilities 


Name 

Used by SMG 

Description 

END_DELETE_MODE (ed) 

N 

Ends delete mode 

END_INSERT_MODE (ei) 

N 

Ends insert mode 

END_LINE_DRAWING_CHAR 

Y 

Ends line drawing 
characters 

END-REVERSE 

N 

Ends reverse video 
characters 

END_UNDERSCORE (ue) 

N 

Ends underscore mode 

ERASE_DISPLAY_TO_CURSOR 

N 

Erases display to virtual 
cursor position 

ERASE—LINE—T 0_CURSOR 

N 

Erases line to virtual 
cursor position 

ERASE—T0—END—DISPLAY (cd) 

Y 

Erases to end of display 

ERASE—T0_END—LINE (ce) 

Y 

Erases to end of line 

ERASE_WHOLE_DISPLAY (cl) 

Y 

Erases whole display 

ERASE_WHOLE_LINE 

N 

Erases whole line 

FF-GRAPHIC 

Y 

Uses this character to 
indicate a formfeed when 
control characters are 
displayed rather than 
executed 

HOME (ho) 

Y 

Defines home cursor 

HORIZONT Al_BAR 

Y 

Displays line drawing 
character—horizontal bar 

HT-GRAPHIC 

Y 

Uses this character to 
indicate a horizontal tab 
when control characters 
are displayed rather than 
executed 

INDEX 

N 

Moves the cursor down 1 
line without changing the 
column position (contents 
of the screen will scroll up 
if necessary) 

INIT—STRING (is) 

Y 

Defines terminal 
initialization string 

INSERT_CHAR (ic) 

N 

Accepts an argument n 
and inserts n characters 

INSERT-LINE 

N 

Accepts an argument n 
and inserts n lines 

INSERT-PAD (ip) 

N 

Accepts an argument n 
and inserts n pads after 
character inserted 

KEY_0 

Y 

Returned by keypad 0 in 
applications mode 
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Table 3-4 (Cont.) 

String Capabilities 


Name 

Used by SMG 

Description 

KEY_1 

Y 

Returned by keypad 1 in 
applications mode 

KEY_2 

Y 

Returned by keypad 2 in 
applications mode 

KEY_3 

Y 

Returned by keypad 3 in 
applications mode 

KEY_4 

Y 

Returned by keypad 4 in 
applications mode 

KEY_5 

Y 

Returned by keypad 5 in 
applications mode 

KEY_6 

Y 

Returned by keypad 6 in 
applications mode 

KEY_7 

Y 

Returned by keypad 7 in 
applications mode 

KEY_8 

Y 

Returned by keypad 8 in 
applications mode 

KEY_9 

Y 

Returned by keypad 9 in 
applications mode 

KEY_BACKSPACE (kb) 

N 

Returned by backspace 
key 

KEY_COMMA 

Y 

Returned by keypad 
comma key 

KEY_DOWN_ARROW 

Y 

Returned by down arrow 
key 

KEY_E1 

Y 

Returned by El (editing 
key 1) 

KEY_E2 

Y 

Returned by E2 (editing 
key 2) 

KEY_E3 

Y 

Returned by E3 (editing 
key 3) 

KEY_E4 

Y 

Returned by E4 (editing 
key 4) 

KEY_E5 

Y 

Returned by E5 (editing 
key 5) 

KEY_E6 

Y 

Returned by E6 (editing 
key 6) 

KEY_ENTER (k) 

Y 

Returned by keypad enter 
key 

KEY_F1 

Y 

Returned by FI (function 
key 1) 

KEY_F20 

Y 

to F20 (function key 20) 

KEY_LABEI_FI 

Y 

Legend on FI (function 
key 1) 

KEY_LABEI_F20 

Y 

to F20 (function key 20) 
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Table 3-4 (Cont.) String Capabilities 


Name 

Used by SMG 

Description 

KEY_LEFT_ARROW (kl) 

Y 

Returned by left arrow 
key 

KEY—MINUS 

Y 

Returned by keypad 
minus key 

KEY—PERIOD 

Y 

Returned by keypad 
period key 

KEY_PF1 

Y 

Returned by PF1 key 

KEY_PF2 

Y 

Returned by PF2 key 

KEY_PF3 

Y 

Returned by PF3 key 

KEY_PF4 

Y 

Returned by PF4 key 

KEY_RIGHT_ARROW (kr) 

Y 

Returned by right arrow 
key 

KEY_UP_ARROW (ku) 

Y 

Returned by up-arrow key 

LEFT_T_CHAR 

Y 

Displays line drawing 
character—left t 

LF_GRAPHIC 

Y 

Uses this character to 
indicate a linefeed when 
control characters are 
displayed rather than 
executed 

LIGHT_SCREEN 

Y 

Makes screen background 
color light (reverse video) 

LOWER_LEFT_CORNER 

Y 

Displays line drawing 
character—lower left 

corner 

LOWER_RIGHT_CORNER 

Y 

Displays line drawing 
character—lower right 
corner 

NAME 

Y 

Defines terminal name— 
must be the first field in 
the entry 

NEWLINE_CHAR (nl) 

N 

Defines newline character 

NEXT_LINE 

N 

Displays next line 

PAD_CHAR (pc) 

N 

Defines pad character (if 
other than null) 

PRINT-SCREEN 

N 

Print contents of screen 

PRIVATE—STR—1 

N 

User-defined capability 1 

PRIVATE—STR—10 

N 

to 10 

REQUEST_CURS0R_P0SITI0N 

N 

Requests the active 
cursor position 

RESTORE-CURSOR (te) 

N 

Restores cursor to 
previously saved position 
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Table 3—4 (Cont.) String Capabilities 


Name 

Used by SMG 

Description 

REVERSE_INDEX 

N 

Moves the cursor to 
the same horizontal 
position on the preceding 
line (contents of the 
screen will scroll down if 
necessary) 

RIGHT_T_CHAR 

Y 

Displays line drawing 
char—right t 

SAVE_CURSOR (ti) 

N 

Saves cursor position 

SCROLI_FORWARD (sf) 

N 

Accepts an argument n 
and scrolls forward n lines 

SCROLLREVERSE (sr) 

Y 

Accepts an argument n 
and scrolls backward n 
lines 

SEI_ER ASE—T 0_END_DISPLA Y 

N 

Selectively erases 
from cursor to end of 
screen (does not change 
attributes) 

SEI_ER ASE_T 0_END_LINE 

N 

Selectively erases from 
cursor to end of line (does 
not change attributes) 

SEI_ERASE_WHOLE_DISPLAY 

N 

Selectively erases entire 
screen (does not change 
attributes) 

SEI_ERASE_WHOLE_LINE 

N 

Selectively erases entire 
line (does not change 
attributes) 

SET_APPLICATION_KEYPAD (ks) 

Y 

Begins application keypad 
mode 

SET_CHAR_NOT_SEI_ERASE 

N 

Designates all subsequent 
characters as not 
selectively eraseable 

SET_CHAR_SEI_ERASE 

N 

Designates all subsequent 
characters as selectively 
eraseable 

SET_CURSOR_ABS (cm) 

Y 

Directs cursor addressing 
(accepts arguments row 
and column) 

SET_CURSOR_OFF 

N 

Sets cursor to invisible 

SET_CURSOR_ON 

N 

Sets cursor to visible 

SET_NUMERIC_KEYPAD (ke) 

Y 

Ends application keypad 
mode (resumes numeric 
keypad mode) 

SET_ORIGIN_ABSOLUTE 

N 

Allows cursor positioning 
outside of current 
scrolling region 
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Table 3-4 (Cont.) String Capabilities 


Name 

Used by SMG 

Description 

SET_ORIGIN_RELATIVE 

N 

Prohibits cursor 
positioning outside of 
current scrolling region 

SET_PRINTER_OUTPUT 

N 

Sends output to printer 
port rather than screen 

SET_SCREEN_OUTPUT 

N 

Resets output to terminal 
screen 

SET_SCROLI_REGION (cs) 

Y 

Sets scrolling region 
(accepts arguments 
top margin and bottom 
margin) 

SET_TAB 

N 

Sets tab at current 
column 

SINGLE_HIGH 

Y 

Changes this line to single 
high, single wide 

TAB_CHAR (ta) 

N 

Defines tab character 
(other than Ctrl 1 or tab 
with padding). Note 
that this field should be 
used only for non-ASCII 
terminals 

TOP_T_CHAR 

Y 

Displays line drawing 
char—top t 

TRUNCATION_ICON 

Y 

Defines the character 
that indicates overflow 
characters were truncated 

UNDERLINE_CHAR (uc) 

N 

Underlines a character 

UPPER_LEFT_CORNER 

Y 

Displays line drawing 
character—upper left 
corner 

UPPER_RIGHT_CORNER 

Y 

Displays line drawing 
character—upper right 
corner 

VERTICAl_BAR 

Y 

Displays line drawing 
character—vertical bar 

VT—GRAPHIC 

Y 

Defines the character that 
indicates a vertical tab 
when control characters 
are displayed rather than 
executed 

WIDTH_N ARROW 

Y 

Sets terminal width to 
narrow size (usually 80 
columns) 

WIDTH_WIDE 

Y 

Sets terminal width to 
wide size (usually 132 
columns) 
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Because string capability fields often include nonprinting characters, the 
following conventions are used to make it easy to insert these characters in a 
capability string. 


Special Character 

Meaning 

$ 

Escape (ASCII decimal value 27) 

- 

Control 

& 

CSI 

@ 

SS3 


Thus to create a capability string that contains an escape character, you simply 
insert a dollar sign at that position. To create a capability string that contains 
a control character, prefix the character with a caret (~). For example: 

NAME = "VT100" 


STRING 

begin_alternate_char = M ~N", 
end_alternate_char = "”'0", 
erase.whole.display = "$[2J" 


END 

To include any special character in a capability string, place an underscore in 
front of it. (For example, results in a single dollar sign rather than an 
underscore followed by an escape character). The following characters must 
be preceded by an underscore in order to be treated as normal ASCII text: 

• Ampersand (&) 

• Apostrophe (') 

• At sign (@) 

• Quotation mark (") 

• Caret (*) 

• Dollar sign ($) 

• Exclamation point (!) 

• Left parenthesis (() 

I • Underscore (_) 

Note that the Screen Management Facility automatically invokes the graphics 
mode needed to display the line-drawing character set (for example, the 
bottom_t_char, top_t_char, and so on). However, if you call the Foreign 
Terminal routines directly, you are responsible for invoking the required 
graphics mode. 

Padding (for example, with null characters) must sometimes be added to 
a terminal command to allow the terminal sufficient time to execute the 
command. The amount of padding needed depends on the terminal and the 
baud rate. The pad_char capability field is included only for future expansion 
and has no function in this release; padding is the responsibility of the user. 

* UNIX is a trademark of Bell Laboratories. 
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When you call the foreign terminal support routines directly, many of the 
string capability fields use arguments whose values must be specified at run 
time. Further, some arguments also require that arithmetic operations be 
performed when values are substituted for arguments. The following sections 
describe argument substitution and arithmetic operations. 


3.10.2.4 Argument Substitution 

It is frequently necessary to substitute values into a terminal command string. 
For example, setting a scrolling region or moving the cursor ten columns to 
the right requires the run-time substitution of a value; these values cannot 
be stored in the TERMTABLE terminal definition. TERMTABLE provides for 
string substitution by accepting !UL, an $FAO style directive. !UL signifies 
that a value is to be inserted at that point: !UL requests that the TERMTABLE 
interface routine accept an unsigned longword and convert it to ASCII digits 
before substituting it in the capability field string (and thus in the returned 
command string). For example: 

NAME = "VT100" 


STRING 

set_cursor_abs = "$[!UL;!ULH" 


END 

The string defined for the SET_CURSOR_ABS function must have values 
substituted for the two !UL directives; these values specify the row and 
column number at which to set the cursor. You specify these run-time 
arguments as an optional longword vector argument to the SMG$GET_ 
TERM_DATA procedure. The first entry in the vector contains the number 
of arguments that follow. Thus, the first entry is 2, the second entry is the 
desired row number and the third entry is the desired column number. The 
SMG$GET_TERM—DATA procedure converts the first optional data item (the 
second item in the vector) to ASCII digits and substitutes them for the first 
!UL directive; it converts the second optional data item and substitutes it for 
the second !UL directive, and so on. 


3.10.2.5 Arithmetic Operations 

In addition to argument substitution, terminal command sequences may 
also require arithmetic operations. To perform an argument substitution and 
arithmetic operation, the TERMTABLE entry requires a different scheme than 
for argument conversion and substitution. 

To perform both argument substitution and arithmetic operations, you use an 
opening parenthesis, a percent sign (to indicate the point of substitution), an 
arithmetic operator, an operand, and a closing parenthesis. For example: 

NAME = "VT52" 


STRING 

8et_cur8or_abs * "$Y(%1+31) C/,2+31) " 


END 
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Values to be substituted into the expression are passed with the SMG$GET_ 
TERM_DATA procedure, in the same way as for argument substitution alone, 

The percent sign is always followed by an integer number which indicates 
the order in which arguments should be substituted. This example shows 
the string that directly positions the cursor on a VT52, where a bias must be 
added to the row and column numbers. The following table summarizes the 
characters used in arithmetic operations: 


Character 

Meaning 

( 

Beginning of arithmetic expression 

%n 

Substitute nth user argument 

+ 

Arithmetic addition operator 

- 

Arithmetic subtraction operator 

* 

Arithmetic multiplication operator 

/ 

Arithmetic division operator 

> 

End of arithmetic expression 


Note that longword integers should be sufficient to express screen 
coordinates. Expressions are evaluated from left to right; there is no operator 
precedence. 

Spaces between items are not significant; they may be used wherever desired 
to improve readability. 


3.10.2.6 Capability Fields Used by Screen Management 

The tables in Section 3.10.2 show whether or not the Screen Management 
Facility may request a particular capability string. Some functions, such as 
wide characters or line drawing, will be requested only if the user calls the 
screen management routines which output wide text or draw lines. If all you 
want to do is write normal text to the screen, only the following set of fields 
need be defined: 

Essential Capabilities 

• NAME 

• SET_CURSOR_ABS 

If SET_CURSOR—ABS is omitted, SMG treats the terminal as a hardcopy 
device. (For more information on using SMG with a hardcopy device, refer to 
SMG$SNAPSHOT.) 

SMG operation will be more efficient if the following optional capabilities are 
also provided: 

• ERASE _TO—END-DISPLAY 

• ERASE _T O—END—LINE 

• SET-SCROLLING -REGION 

If you do not include ERASE _TO_END-DISPLAY, ERASE _TO_END_ 
LINE, or SET—SCROLLING—REGION, the Screen Management Facility 
will write blanks to perform these functions. However, writing blanks is a 
slower operation. Similarly, hardware scrolling also improves output speed; 
if scrolling is not available, the Screen Management Facility must rewrite the 
entire screen. 
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The Screen Management Facility uses the ASCII character set. If your 
terminal has a line-drawing character set, you should define the line drawing 
characters (BOTTOM_T_CHAR, HORIZONTAL _BAR, etc). If line-drawing 
characters are not defined, SMG will use normal ASCII characters to draw 
borders. 

The Screen Management Facility also relies on the terminal characteristics 
maintained by the terminal driver. You can change these characteristics 
with the DCL SET TERMINAL command. For example, if you type SET 
TERMINAL/NOTAB, then the Screen Management Facility does not send 
tabs to the terminal. 


3.10.3 SMG$ Input Support for Foreign Terminals 

A foreign terminal is any terminal for which the device type is not one of the 
standard DIGITAL terminals recognized by VMS, or any terminal on which 
the ANSI—CRT characteristic is not set. 

When you use a DIGITAL (or ANSI) terminal, typing a special key such as 
a function key or a keypad key sends an escape sequence (as defined by 
the ANSI standard) to the VMS terminal driver. The VMS terminal driver 
understands this ANSI standard and interprets the escape sequence according 
to this standard. Thus, the VMS terminal driver knows how long the escape 
sequence is and what characters are allowed in which positions in that 
sequence. 

The VMS terminal driver does not echo any of the printing characters from 
the sequence because those characters are understood as part of the escape 
sequence. They are not interpreted as normal keys; normal keys would be 
echoed unless the TRM$M_TM_NOECHO modifier was specified. 

The VMS terminal driver returns to SMG$ the sequence, the length of the 
sequence, and the number of characters entered before the function key was 
typed. SMG$ determines which key was typed by comparing the sequence 
and its length against the list of key definitions for that particular terminal in 
TERMTABLE.EXE. This code is returned to the user in the format SMG$K_ 
TRM—xxx, where xxx is used to specify the particular key. 

When you type a special key such as a function key or a keypad key on a 
foreign terminal, a non-ANSI sequence is sent to the VMS terminal driver. 

If this sequence starts with a control character, the VMS terminal driver 
interprets this character as a terminator. (By default all control characters 
are terminators unless you use a terminator mask to specify otherwise.) 

The terminal driver then stops reading characters and returns to SMG$ the 
character, a length of 1, and the number of characters entered before the 
function key was typed. 

SMG$ looks at the returned character. If it is a control character, SMG$ 
looks in the typeahead buffer for the next characters of the sequence. If there 
are characters in the typeahead buffer, SMG$ will read one character from 
the typeahead buffer, append it to the control sequence it has already, and 
check this new sequence against the list of key definitions for this terminal 
in TERMTABLE.EXE to determine which key was typed. If the sequence 
is not matched (SMG$K_TRM_xxxx), the next character is read from the 
typeahead buffer. This continues until a match is found or the typeahead 
buffer is empty. Since the terminal driver does not know about this sequence, 
any printable characters in the sequence are echoed by the terminal driver 
unless the noecho modifier was specified by the user. Because SMG$ does 
not know what characters will make up this sequence, it forces line-editing 
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to be disabled to allow the actual characters that make up the sequence to be 
returned to SMG$. 

Terminals whose special keys send a sequence that does not start with 
a control character are not supported by SMG$ for input. Changing the 
terminator mask to exclude the control character that starts the function key 
sequence is not supported. In addition, the performance of a foreign terminal 
doing input will not be as good as a DIGITAL terminal doing the same input 
since SMG$ must parse the sequence in place of the VMS terminal driver. 


3.10.4 Examples 


! Private versions of DIGITAL terminal definitions 

! 

NAME = 'myvtlOO' 

BOOLEAN 
ansi_crt = 1, 

NUMERIC 
rows = 24, 
wide_screen_columns 
STRING 

begin_alternate_char * "~N", 
end_alternate_char = "~0", 
erase_whole_display = "$[2J", 
init.string ■ , 

set_cursor_abs = "$[!UL;!ULH" 

END 

NAME = "MYVT52" 

BOOLEAN 
ansi_crt = 0, 

NUMERIC 
rows = 24, 
wide_screen_columns 
STRING 

begin_alternate_char = "$F" 
end_alternate_char = "$G", 

erase_whole_display = "$Y(32)(32)$J", !position to 1,1; then erase 

set_cursor_ab8 = "$Y('/,1+31) (*/.2+31) " 

END 

For the set cursor sequence listed for a VT100 (MYVT100), the string returned 
depends on the values provided in the argument vector supplied with the 
call to the SMG$GET_TERM_DATA procedure. For example, to position 
the cursor to row 3 and column 12, you supply these longword values as 
the second and third entries in the vector (the first entry is the number of 
values that follow). The SMG$GET_TERM_DATA procedure converts these 
longword values into their ASCII values and inserts the converted values into 
the string returned at the point of the respective !UL directives. 

For the set cursor sequence listed for a VT52 (MYVT52), the string returned 
depends not on argument substitution, but on an arithmetic operation 
(because the VT52 requires biasing). The arithmetic operator (%n+31) is 
used to add 31 (decimal) to the row and column numbers supplied in entries 
2 and 3 in the argument vector for the SMG$GET_TERM_DATA procedure. 

The INIT—STRING field in MYVT100 is included to point out that the 
parenthesis is normally treated as a special character indicating an arithmetic 
expression. A parenthesis must be preceded by an underscore in order to be 
interpreted as a normal text character. Thus the string "$_(B" yields ESC(B, a 
command that designates the ASCII character set into GO. 


dec.crt = 1 
columns = 80, 

= 80 


dec_crt * 1 

columns = 80, 
= 132 
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The ERASE—WHOLE—DISPLAY sequence for MYVT52 shows that it may be 
necessary to combine sequences in order to provide a certain function. The 
MYVT52 does not have a command that erases the entire screen. However, 
you can erase the entire screen by homing the cursor and then using the 
command that erases from the current position to the end of the screen. 

The following BASIC example program uses the LIB$GETDVI RTL routine to 
ascertain the type of terminal associated with SYS$OUTPUT. The program 
then uses the foreign terminal routines to place the cursor at the twelfth 
screen line and to erase to the end of the screen. Note that the program 
detects whether these capabilities are available for the terminal and displays 
an error message if they are not. 


10 ! Program to call the Termtable interface routines 

j 

! This program will set the cursor to row 12 column 1, 

! and erase to the bottom of the screen. If the cursor 
! positioning or erasing to the end of the screen 
! capabilities are not defined, a message will be output. 

OPTION TYPE = EXPLICIT, SIZE = INTEGER LONG 

EXTERNAL INTEGER FUNCTION SYS$ASSIGN, SYS$DASSGN, SYS$QI0W 

EXTERNAL INTEGER FUNCTION LIB$GETDVI, LIB$GET_EF, LIB$FREE_EF 

EXTERNAL INTEGER FUNCTION SMG$INIT_TERM_TABLE_BY_TYPE, SMG$GET_TERM_DATA 

EXTERNAL INTEGER CONSTANT IO$_WRITEVBLK, DVI$_DEVTYPE 


DECLARE INTEGER CONSTANT SMG$K_SET_CURSOR_ABS = 570 
DECLARE INTEGER CONSTANT SMG$K_ERASE_TO_END_DISPLAY = 472 

COMMON (buf) STRING Data.buffer = 20 ! buffer to hold terminal data 


DECLARE INTEGER Sys.status, & 

Chan, & 

Term_type, & 

Term_table_addr, & 

Arg.vector (2), & 

Ret.len, & 

Event.flag 


! Assign a channel for LIB$GETDVI and SYS$QI0W. 

Sys.status * SYS$ASSIGN ('SYS$OUTPUT•, Chan, , , ) 

IF (Sys.status AND 1'/,) = 0'/. 

THEN 

PRINT "Error from SYS$ASSIGN : ";Sys.status 
GOTO Done 
END IF 

! Get the terminal type. 

Sys.status * LIB$GETDVI (DVI$_DEVTYPE ! request item code & 

.Chan ! channel assigned to SYS$OUTPUT & 

, ! omit device name & 

.Term.type) ! place to return type 

IF (Sys.status AND 1'/,) = 0'/, 

THEN 

PRINT "Error from LIB$GETDVI : ";Sys.status 
GOTO Done 
END IF 

! Get the definition for the type of terminal we are running on. 

Sys.status = SMG$INIT_TERM_TABLE_BY_TYPE (Term.type, Term.table.addr) 

IF (Sys.status AND 1*/.) = 0'/, 

THEN 

PRINT "Error getting terminal definition : ";Sys.status 
GOTO Done 
END IF 


«* 
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! Get the sequence to position the cursor to 12,1 


Arg_vector (0) = 27. 
Arg.vector (1) = 127, 
Arg_vector (2) = 17. 


number of args to follow 
row number 
column number 


Sys.status = SMG$GET_TERM_DATA k 

( Term_table_addr ! addr of terminal definition k 

,SMG$K_SET_CURSOR_ABS ! request code k 

,207. ! max buffer length k 

,Ret_len ! length of sequence returned k 

,Data_buffer BY REF ! buffer to hold sequence k 

,Arg_vector (0) ) ! optional vector with 

! row and column numbers 


IF (Sys.status AND 17.) = 07. 

THEN 

PRINT "Error getting cursor sequence : ";Sys_status 
GOTO Done 
END IF 


IF Ret.len = 07. 

THEN 

PRINT "Cursor sequence not available" 

GOTO Done 
END IF 

! Get a unique event flag number 
Sys.status = LIB$GET_EF (Event_flag) 

IF (Sys.status AND 17.) = 07. 

THEN 

PRINT "Unable to allocate an event flag" 

GOTO Done 
END IF 

! Output the cursor sequence to the terminal. 

Sys.status = SYS$QI0W ( Event.flag BY VALUE ! event flag number k 


,Chan BY VALUE ! channel number & 

,I0$_WRITEVBLK BY VALUE ! function code k 

, , , ! no iosb, k 

! ast routine, k 

! or argument k 

,Data_buffer BY REF ! buffer to output k 

,Ret_len BY VALUE ! bytes returned k 


, , , , ) ! null arguments 

IF (Sys.status AND 17.) = 07. 

THEN 

PRINT "Error from SYS$QI0W : ";Sys.status 
GOTO Done 
END IF 


! Get the sequence to erase from current cursor to end of screen. 

Sys.status = SMG$GET_TERM_DATA k 

( Term.table.addr ! addr of terminal definition k 
,SMG$K_ERASE_TO_END_DISPLAY ! request code k 

,207. ! max buffer length k 

.Ret.len ! bytes returned k 


.Data.buffer BY REF) ! buffer for sequence 

IF (Sys.status AND 17.) = 07. 

THEN 

PRINT "Error getting erase sequence : ";Sys.status 
GOTO Done 
END IF 


IF Ret.len = 07. 

THEN 

PRINT "Erase sequence not available" 
GOTO Done 
END IF 
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! Output the erase sequence to the terminal. 


Sys.status = SYS$QIOW (Event.flag BY VALUE ! 

,Chau BY VALUE ! 

,IO$_WRITEVBLK BY VALUE ! 


,Data_buffer BY REF ! 
,Ret_len BY VALUE ! 
. . . . ) • 


event flag number & 

channel number A 

function code value & 

no iosb, A 

ast routine, & 

or argument & 

buffer to output & 

bytes in buffer & 

null arguments 


IF (Sys.status AND 1'/,) = 0'/. 

THEN 

PRINT "Error from SYS$QI0W : Sys.status 

GOTO Done 
END IF 

! Deassign the channel. 

Sys.status = SYS$DASSGN (Chan BY VALUE) 


IF (Sys.status AND 1'/.) = 0'/, 

THEN 

PRINT "Error from SYS$DASSGN : ";Sys.status 
GOTO Done 
END IF 

! Deallocate event flag so other programs can use it. 


Sys.status = LIB$FREE_EF (Event.flag) 


IF (Sys.status AND 1'/.) = 0*/. 

THEN 

PRINT "Unable to deallocate event flag" 
GOTO Done 
END IF 

32767 Done: END 


3.10.5 Compiling TERMTABLE.TXT 

Accessing an ASCII file for each screen program is inefficient because the 
ASCII text must be processed as binary information before it can be returned 
as a string ready for the terminal. To avoid paying the price of this processing 
at the start of every image, TERMTABLE.TXT is "precompiled" into the 
required binary format. A screen application then gets its terminal sequences 
from the precompiled binary capabilities file. 

You compile TERMTABLE.TXT by running the 
SYS$SYSTEM:SMGBLDTRM.EXE program. This utility accepts 
TERMTABLE.TXT as an input file and creates TERMTABLE.EXE as an output 
file. 

Internally, the compiled terminal capabilities are stored as a table in a file 
which is mapped as a permanent global section. Thus, user programs map to 
the global section, rather than having their own copy of the capabilities data. 

If a user compiles a private TERMTABLE.TXT from his or her own directory, 
the interface routines access it by mapping it as a temporary section. 
TERMTABLE interface routines look for a definition in the temporary section 
before looking in the system's permanent global section. 

Note that system managers may want to coordinate terminal definitions so 
that non-standard definitions are confined to a user's private area. 

Most users do not have the privilege to create a permanent global section. 

A short program, SYS$SYSTEM:SMGMAPTRM.EXE, which will map the 
compiled TERMTABLE as a global section, is part of the standard VMS start¬ 
up procedure. In order to map an updated TERMTABLE.EXE as the global 
section, the existing global section must first be deleted. Deleting 
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the global section while the system is active may cause a user's program 
to fail; therefore the system must be rebooted in order to make an updated 
TERMTABLE.EXE the default. 

To reduce compiling time and the size of the resulting global section, the 
terminal definitions in SYS$SYSTEM:TERMTABLE.TXT should be kept to 
a minimum. Only the types of terminals that are actually attached to the 
computer system should be defined. 


3.10.6 Support for SET and SHOW TERMINAL Commands 

The DCL SET TERMINAL command is the mechanism for setting your 
terminal to conform to a TERMTABLE definition. SET TERMINAL causes the 
following three fields to be retrieved from the TERMTABLE database and set 
for your terminal. 

1 Terminal type—A signed integer assigned by the system and associated 
with a particular device type 

2 Width—The number of columns on the physical screen 

3 Page size—The number of rows in the screen 

In addition, if the corresponding Boolean capability is set in the terminal 
definition, the following flags are set. 

• ADVANCED—VIDEO 

• ANSI—CRT 

• BLOCK-MODE 

• DEC—CRT 

• EDIT 

• EIGHT-BIT 

• FORM 

• FULLDUP 

• LOWERCASE 

• REGIS 

• SCOPE 

• SIXEL-GRAPHICS 

• SOFT-CHARACTERS 

• TAB 

If any of these fields are missing from your definition, the previous setting 
for that characteristic is retained; SET TERMINAL does not try to set 
that characteristic for your terminal. You should include all of the above 
capabilities in your definitions to avoid unpredictable settings. 

SET TERMINAL will operate as it always has for known terminals such as 
the VT200—series, VT100, and VT52. When SET TERMINAL encounters an 
unknown device name, such as HAZELTINE, it will search TERMTABLE 
for a definition with this name. Notice that your definitions must have 
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names other than the names that SET TERMINAL currently recognizes. The 
terminals currently recognized are listed below: 


LA 12 

LQP02 

VT102 

LA34 

VT05 

VT 125 

LA36 

VT52 

VT 131 

LA38 

VT55 

VT132 

LA 100 

VT100 

VT200—SERIES 

LA 120 

Unknown 

VT101 

FT 1 through FT8 


If SET TERMINAL finds the device name in its own internal tables, it does 
not search the TERMTABLE database. 

Since the SET TERMINAL recognizes only the first 15 characters of a device 
name, you may want to limit your terminal names to 15 characters. 

The SET TERMINAL/DEVICE=name command causes the TERMTABLE 
database to be searched for the named terminal, if that terminal is unknown 
to VAX/VMS. It then sets various terminal characteristics, as shown in 
the following table, based on the presence of these capabilities in the 
TERMTABLE database. 


Capability Field 

Terminal Characteristic 

LOWERCASE 

LOWERCASE 

PHYSICAI_T ABS 

TABS 

SCOPE 

SCOPE 

EIGHT-BIT 

EIGHTBIT 

PHYSICAI_FF 

FORM 

FULLDUP 

FULLDUP 

SIXELGRAPHICS 

SIXEL 

SOFT_CHARACTERS 

SOFT 

ANSI—CRT 

ANSI—CRT 

REGIS 

REGIS 

BLOCK_MODE 

BLOCK 

ADVANCED_VIDEO 

AVO 

EDIT—MODE 

EDIT 

DEC—CRT 

DEC—CRT 


The SET TERMINAL/DEVICE_TYPE= format must be used with 
TERMTABLE terminals. SET TERMINAL/name is an old format that works 
for a small set of device names, and is maintained only for compatibility with 
previous versions of VAX/VMS. 

SCRFT.MAR is an undocumented, unsupported skeleton program which is 
not supported by the Screen Management Facility. The customer must fill 
in this program with code to support the particular type of non-DIGITAL 
terminal. When the Screen Package (the Screen Management Facility's 
predecessor) detects a terminal type of FT1 through FT8, it invokes the 
SCRFT image with the terminal type and a function code. SCRFT constructs 
the requested escape sequence and passes it back to the Screen Package, 
which outputs it by using $QIO. Users who want to continue using this old 
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style of foreign terminal support must continue to use the Screen Package 
(SCR$ and LIB$ procedures). 



3.10.7 TERMTABLE Interface Routines 

In essence, TERMTABLE.EXE is a database containing information about any 
number of different types of terminals. You extract information from this 
database in three steps: 

1 Initialize the database for a given type of terminal. 

2 Retrieve the information about that terminal type (this step might be 
repeated any number of times). 

3 End access to the database. 

Note that when using screen management procedures to perform I/O to 
foreign terminals, you need only create the proper TERMTABLE entries for 
the foreign terminals you use. The steps listed above are necessary only 
when your program is doing I/O directly to foreign terminals. 

The first step can be performed in either of two ways. You can either 
pass a string that contains a terminal name (for example, "VT100") to the 
SMG$INIT_TERM_TABLE procedure, or you can pass a value returned 
by the VAX/VMS system service SYS$GETDVI to the SMG$INIT_TERM__ 
TABLE_BY_TYPE procedure. The returned value may be a symbolic terminal 
type (for example, TT$_VT100 or TT$_VT52) or a value assigned by the 
SMG$ foreign terminal routines to designate a particular foreign terminal. 

The second step requires that you call the SMG$GET__TERM__DATA 
procedure. This routine extracts a command string (for example, an escape 
sequence) from TERMTABLE and stores it in a buffer you provide. It is then 
your responsibility to write the command string to the terminal. Note that it 
may be necessary to call SMG$GET_TERM_DATA many times; each time 
you receive the command sequence to perform a different operation. Note 
that you should also call SMG$GET_TERM_DATA each time you want to 
use a capability string that requires a substitution or arithmetic operation for 
an argument. However, you may want to save the static capability strings in 
your program's local storage. These static capability strings can be retrieved 
once and used any number of times. 

The third step is optional; it merely frees the virtual memory used to access 
the information in the database. 

Note that the DCL SET and SHOW TERMINAL commands now recognize 
any name defined in TERMTABLE, as well as the current set of valid 
VAX/VMS terminal names. If you use the SET TERMINAL/DEVICE=name 
command to specify a terminal that is unknown to VAX/VMS, the 
TERMTABLE database is searched for the named terminal. 

Two routines are provided to obtain the address of a specific terminal 
definition. SMG$INIT_TERM_TABLE accepts a terminal name as input; 
SMG$INIT_TERM_TABLE_BY_TYPE accepts a device type as input. Each 
maps to a specific terminal entry in the TERMTABLE.EXE section. These 
routines return this address to the caller for use in future calls. 

SMG$GET_TERM_DATA accepts the address of the compiled TERMTABLE 
database and a request code. The request code is used as an index into the 
data to retrieve the appropriate escape sequence. Some sequences are static; 
they do not contain any variable information and are simply copied into the 
caller's buffer. Variable sequences, which include a ! or % directive, cause 
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additional processing to take place. An example of a variable sequence is the 
VT100 set cursor command: the required binary row and column numbers 
must be converted to ASCII for the set cursor sequence. SMG$GET_TERM— 
DATA uses the optional input arguments to do the conversion before copying 
the sequence to the caller's buffer. 

Note that if you do not provide any optional input arguments to SMG$GET_ 
TERM-DATA, it uses a default of 1 for each argument that the capability 
requires. However, you cannot supply some of the optional arguments 
and accept the default for others—you must supply all or none of them. 
However, in SMG$GET_TERM—DATA, if you provide arguments where 
none are needed, the number of additional arguments will be used as a repeat 
count. SMG$GET_NUMERIC—DATA provides a simplified interface for 
users who wish to obtain numeric or boolean data only. 

When all terminal I/O has been completed, SMG$DEL_TERM—TABLE 
can be called to unmap a temporary section. This call is optional; it simply 
releases virtual address space if a temporary section was used and has no 
effect if a global section was used. Note that virtual memory would be 
deallocated at image exit anyway. This routine is useful only if you do 
not need TERMTABLE for the duration of your program; releasing virtual 
memory may make it available for re-use by your program. 

A skeleton TERMTABLE.TXT is shipped with the interface routines. 
SMGTERMS.TXT, which defines DIGITAL terminals, is also provided. 

The skeleton TERMTABLE.TXT uses the REQUIRE directive to include the 
separate source file SMGTERMS.TXT. Thus, only non-DIGITAL terminals are 
actually defined in the TERMTABLE.TXT source file. 

Note that SMGTERMS.TXT should not be modified by users. 


3.11 Examples of Calling SMG$ Procedures 

This section contains examples demonstrating how to call the procedure 
SMG$READ_KEYSTROKE from all major VAX languages. Other SMG$ 
procedures, such as SMG$CREATE_VIRTUAL—DISPLAY, SMG$CREATE_ 
PASTEBOARD, SMG$CREATE_VIRTUAL—KEYBOARD, SMG$PASTE_ 
VIRTUAL—DISPLAY, and SMG$PUT_LINE are also used throughout these 
examples. 

Example 3-1 demonstrates the use of SMG$READ_KEYSTROKE from an 
Ada program. This program also uses SMG$CREATE_VIRTUAL—DISPLAY, 
SMG$CREATE_PASTEBOARD, SMG$CREATE_VIRTUAL—KEYBOARD 
SMG$PASTE_VIRTUAL—DISPLAY, and SMG$PUT-LINE. 
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Example 3-1 Using SMG$ Procedures in VAX Ada 


with SYSTEM, CONDITION_HANDLING; use SYSTEM; 
package SMG is -- declarations of SMG$ routines used 

procedure CREATE_VIRTUAL_DISPLAY ( 

STATUS: out CONDITION.HANDLING.COND_VALUE_TYPE; 

ROWS, COLUMNS: INTEGER; 

DISPLAYED: out INTEGER; 

DISPLAY.ATTRIBUTES, VIDEO.ATTRIBUTES, CHAR.SET: UNSIGNED.LONGWORD 
:= UNSIGNED.LONGWORD'NULL.PARAMETER); 
pragma INTERFACE (SMG, CREATE.VIRTUAL.DISPLAY); 
pragma IMPORT.VALUED.PROCEDURE 

(CREATE_VIRTUAL_DISPLAY, "SMGSCREATE.VIRTUAL.DISPLAY"); 

procedure CREATE.PASTEBOARD ( 

STATUS: out CONDITION.HANDLING.COND_VALUE_TYPE; 

PASTEBOARD.ID: out INTEGER; 

OUTPUT.DEVICE: STRING := STRING'NULL.PARAMETER; 

ROWS. COLUMNS: INTEGER := INTEGER'NULL.PARAMETER; 
PRESERVE.SCREEN.FLAG: BOOLEAN := BOOLEAN'NULL.PARAMETER); 
pragma INTERFACE (SMG, CREATE.PASTEBOARD); 
pragma IMPORT.VALUED.PROCEDURE 

(CREATE.PASTEBOARD. "SMG$CREATE_PASTEBOARD"); 

procedure CREATE.VIRTUAL.KEYBOARD ( 

STATUS: out CONDITION_HANDLING.COND_VALUE.TYPE; 

KEYBOARD.ID: out INTEGER; 

FILESPEC, DEFAULT.FILESPEC, RESULTANT.FILESPEC: STRING 
:= STRING'NULL.PARAMETER); 
pragma INTERFACE (SMG. CREATE.VIRTUAL.KEYBOARD); 
pragma IMPORT.VALUED.PROCEDURE 

(CREATE.VIRTUAL.KEYBOARD, "SMG$CREATE_VIRTUAL_KEYBOARD"); 
procedure PASTE.VIRTUAL.DISPLAY ( 

STATUS: out CONDITION_HANDLING.COND_VALUE.TYPE; 

DISPLAY.ID, PASTEBOARD.ID: INTEGER; 

ROW, COLUMN: INTEGER); 

pragma INTERFACE (SMG, PASTE.VIRTUAL.DISPLAY); 
pragma IMPORT.VALUED.PROCEDURE 

(PASTE.VIRTUAL.DISPLAY, "SMG$PASTE_VIRTUAL_DISPLAY"); 

procedure READ.KEYSTROKE ( 

STATUS: out CONDITION_HANDLING.COND_VALUE.TYPE; 

KEYBOARD.ID: INTEGER; 

TERMINATOR.CODE: out UNSIGNED.WORD; 

PROMPT: STRING := STRING’NULL.PARAMETER; 

TIMEOUT, DISPLAY.ID: INTEGER := INTEGER'NULL.PARAMETER); 
pragma INTERFACE (SMG, READ.KEYSTROKE); 
pragma IMPORT.VALUED.PROCEDURE 

(READ.KEYSTROKE. "SMGlREAD.KEYSTROKE"); 

procedure PUT.LINE ( 

STATUS: out CONDITION.HANDLING.COND_VALUE.TYPE; 

DISPLAY.ID: INTEGER; 

TEXT: STRING; 

LINE.ADVANCE: INTEGER := INTEGER'NULL.PARAMETER; 

RENDITION.SET, RENDITION.COMPLEMENT: UNSIGNED.LONGWORD 
:= UNSIGNED.LONGWORD'NULL.PARAMETER; 

WRAP.FLAG: BOOLEAN := BOOLEAN'NULL.PARAMETER; 

CHAR.SET: UNSIGNED.LONGWORD := UNSIGNED.LONGWORD'NULL.PARAMETER); 
pragma INTERFACE (SMG, PUT.LINE); 
pragma IMPORT.VALUED.PROCEDURE 
(PUT.LINE, "SMG$PUT_LINE"); 

end SMG; 


(Continued on next page) 
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Example 3-1 (Cont.) Using SMG$ Procedures in VAX Ada 


— This routine demonstrates the use of the SMG$ routines, in particular 
-- SMGlREAD.KEYSTROKE. 

with SMG, STARLET, CONDITION.HANDLING, SYSTEM; 
procedure SMG.DEMO is 

STATUS: CONDITION.HANDLING.COND.VALUE.TYPE; 

PASTEBOARD__1, DISPLAY.l, KEYBOARD. 1: INTEGER; 

TERMINATOR: SYSTEM.UNSIGNED.WORD; 
begin 

-- Create virtual display, pasteboard and virtual keyboard. 

SMG.CREATE.VIRTUAL.DISPLAY (STATUS, ROWS *> 7, COLUMNS *> 60, 
DISPLAY.ID => DISPLAY.l, 

DISPLAY.ATTRIBUTES => STARLET.SMG.M.BORDER); 

SMG.CREATE.PASTEBOARD (STATUS, PASTEBOARD.ID *> PASTEBOARD.1); 

SMG.CREATE.VIRTUAL.KEYBOARD (STATUS, KEYBOARD.ID => KEYBOARD.1); 

— Paste the virtual display at row 3, column 9. 

SMG.PASTE.VIRTUAL.DISPLAY (STATUS, DISPLAY.ID => DISPLAY.l. 
PASTEBOARD.ID => PASTEBOARD.1, ROW => 3. COLUMN *> 9); 

— Write the instructions to the virtual display. 

SMG.PUT.LINE (STATUS. DISPLAY.ID => DISPLAY.l, 

TEXT => "Enter the character K after the » prompt."); 

SMG.PUT.LINE (STATUS. DISPLAY.ID => DISPLAY.l, 

TEXT => "This character will not be echoed as you type it."); 
SMG.PUT.LINE (STATUS. DISPLAY.ID => DISPLAY.l, 

TEXT *> "The terminal character equivalent of K is displayed."); 
SMG.PUT.LINE (STATUS, DISPLAY.ID => DISPLAY.l, 

TEXT =>""); 

-- Read the keystroke from the virtual keyboard. 

SMG.READ.KEYSTROKE (STATUS, KEYBOARD.ID => KEYBOARD.1, 

DISPLAY.ID *> DISPLAY.l. 

TERMINATOR.CODE => TERMINATOR. PROMPT => "»") ; 

-- Display the decimal value of the terminator code. 

SMG.PUT.LINE (STATUS. DISPLAY.ID => DISPLAY.l. 

TEXT *>""); 

SMG.PUT.LINE (STATUS. DISPLAY.ID => DISPLAY.l, 

TEXT => "TERMINAL CHARACTER IS " & 

SYSTEM.UNSIGNED.WORD•IMAGE(TERMINATOR)); 

end SMG.DEMO; 
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Example 3-2 uses SMG$READ_KEYSTROKE to read a keystroke from 
the terminal. This BASIC program also uses SMG$CREATE_VIRTUAL- 
KEYBOARD and SMG$DELETE_VIRTUAL_KEYBOARD. 

Example 3-2 Using SMG$ Procedures in VAX BASIC 


1 OPTION TYPE=EXPLICIT 


This routine demonstrates the use of SMG$READ_KEYSTROKE to read 
a keystroke from the terminal. 

Build this program using the following commands. 

$ BASIC READ.KEY 
$ CREATE SMGDEF.MAR 

.TITLE SMGDEF - Define SMG$ constants 
.Ident /1-000/ 

ISMGDEF GLOBAL 

.END 

$ MACRO SMGDEF 
$ LINK READ.KEY.SMGDEF 


DECLARE LONG KB_ID, RET.STATUS, TERM_C0DE, 
EXTERNAL SUB LIB$SIGNAL( LONG BY VALUE ) 
SUB LIB$STOP( LONG BY VALUE ) 

LONG CONSTANT 


I, TIMER 


EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

EXTERNAL 

LONG, 


LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 

LONG 


CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

CONSTANT 

FUNCTION 

FUNCTION 

FUNCTION 


SS$_TIMEOUT 

SMG$K_TRM_PF1 

SMG$K_TRM_PERIOD 

SMG$K_TRM_UP 

SMG$K_TRM_RIGHT 

SMG$K_TRM_F6 

SMG$K_TRM_F20 

SMG$K_TRM_FIND 

SMG$K_TRM_NEXT_SCREEN 

SMG$K_TRM_TIMEOUT 

SMG$CREATE_VIRTUAL_KEYBOARD( LONG, STRING ) 
SMG$DELETE_VIRTUAL_KEYBOARD( LONG ) 
SMG$READ_KEYSTROKE( LONG, LONG. STRING, & 


LONG ) 


! + 

! Prompt the user for the timer value. A value of 0 will cause 
! the type ahead buffer to be read. 

; - 

INPUT "Enter timer value (0 to read typeahead buffer): TIMER 

! + 

! Establish a SMG connection to SYS$INPUT. Signal any unexpected 
! errors. 


RET.STATUS = SMG$CREATE_VIRTUAL_KEYBOARD( KB_ID, "SYS$INPUT:" ) 
IF (RET.STATUS AND 1%) = OX THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 


Read a keystoke, tell the user what we found. 


(Continued on next page) 
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Example 3-2 (Cont.) Using SMG$ Procedures in VAX BASIC 


RET.STATUS = SMG$READ_KEYSTROKE( KB.ID, TERM.CODE, . TIMER. ) 

IF (RET.STATUS <> SS$_TIMEOUT) AND ((RET.STATUS AND 1%) = 07.) THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 

PRINT "term.code = ";TERM.CODE 
SELECT TERM.CODE 
CASE 0 TO 31 

PRINT "You typed a control character" 

CASE 32 TO 127 

PRINT "You typed: ";CHR$(TERM.CODE) 

CASE SMGSK.TRM.PFl TO SMG$K_TRM_PERIOD 

PRINT "You typed one of the keypad keys" 

CASE SMG$K_TRM_UP TO SMG$K_TRM_RIGHT 

PRINT "You typed one of the cursor positioning keys" 

CASE SMG$K_TRM_F6 TO SMG$K_TRM_F20 

PRINT "You typed one of the function keys" 

CASE SMG$K.TRM_FIND TO SMG$K_TRM.NEXT_SCREEN 
PRINT "You typed one of the editing keys" 

CASE SMG$K_TRM_TIMEOUT 

PRINT "You did not type a key fast enough" 

CASE ELSE 

PRINT "I'm not sure what key you typed" 

END SELECT 
! + 

! Close the connection to SYSlINPUT, and signal any errors. 

i - 

RET.STATUS = SMG$DELETE_VIRTUAL_KEYBOARD( KB.ID ) 

IF (RET.STATUS AND 17.) = 07. THEN 
CALL LIB$SIGNAL( RET.STATUS ) 

END IF 
END 
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The BLISS program shown in Example 3-3 demonstrates the use of 
SMG$READ__KEYSTROKE from a lower-level language. 

Example 3-3 Using SMG$ Procedures in VAX BLISS32 


MODULE READ_SINGLE_CHAR ( MAIN = PERFORM.READ. 

•/.TITLE 'Read a Keystroke from SYS$INPUT' 

IDENT = '1-001' ) = 

BEGIN 


Facility: Example programs 

Abstract: This example program uses the procedure SMG$READ_KEYSTROKE 

to get a single character input from the current SYS$INPUT 
device and then indicates the nature of the input to the user. 

Environment: User mode, AST reentrant 

Author: John Doe Creation Date: 8-Apr-1985 

Modified by: 

1-001 - Original. JD 8-Apr-1985 


General mode addressing must be used for external references. 


%SBTTL 'Declarations' 

SWITCHES ADDRESSING.MODE (EXTERNAL=GENERAL. NONEXTERNAL-WORD_RELATIVE); 
! + 

! Obtain SMG$, SS$, etc. definitions. 

j - 

LIBRARY 'SYS$LIBRARY:STARLET'; 

! + 

! Use the TUTIO package for the purposes of this small example. 

j - 

REQUIRE 'SYS$LIBRARY:TUTIO'; 

! + 

! Declare Screen ManaGement procedures used by this program, as well as 
! any other external procedures. 

j - 

EXTERNAL ROUTINE 

SMG$CREATE_VIRTUAL_KEYBOARD, 

SMG$DELETE_VIRTUAL_KEYBOARD, 

SMG$READ_KEYSTROKE. 

LIBISIGNAL : NOVALUE; 


! Define a convenient way to check the return status from a procedure. 

MACRO CHECK (X) = 

IF NOT X 
THEN 

LIB$SIGNAL (X) 

y.; 


(Continued on next page) 
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Example 3-3 (Cont.) Using SMG$ Procedures in VAX BLISS32 


*/,SBTTL 'Routine PERFORM_READ' 

ROUTINE PERFORM_READ: NOVALUE = 

! + 

! Functional Description: 

! 

! This procedure uses Screen Management I/O to get a single character 
! input from the current SYS$INPUT device, and then processes is by 
! what its character or termination code is. 

j 

! Calling Sequence: 

j 

! Not callable 

i 

! Formal Arguments: 

j 

! Not Applicable 

j 

! Implicit Inputs: 

i 

! None 

j 

! Implicit Outputs: 

! 

! None 

i 

! Side Effects: 

! 

! Any error returned by Screen Management procedures except for 
! SSl.TIMEOUT will be signaled. 

BEGIN 

LITERAL 
ZERO = 0; 

LOCAL 

KBID : INITIAL(O), 

TERM.CODE : INITIAL(0), 

TIMER.VALUE : INITIAL(0), 

SMG.STATUS; 


Obtain a read timeout value. 


TIMER.VALUE = 10; 

• + 

! Establish a Screen ManaGed connection to SYS$INPUT. 

j - 

SMG.STATUS = SMG$CREATE_VIRTUAL_KEYBOARD (KBID, USCID'SYSl INPUT'); 
CHECK (.SMG.STATUS); 

! + 

! Read a keystroke and tell the user what was found. 

! - 

SMG.STATUS = SMG$READ_KEYSTROKE (KBID, TERM.CODE, ZERO. TIMER.VALUE); 
IF (.SMG.STATUS NEQ SS$_TIMEOUT) 

THEN 

CHECK (.SMG.STATUS); 


(Continued on next page) 
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Example 3-3 (Cont.) Using SMG$ Procedures in VAX BLISS32 


SELECTONE .TERM.CODE OF 
SET 

[0 TO 31]: 

TTY_PUT_QU0 ('You typed a control character.'); 

[32 TO 127]: 

TTY.PUT.QUO ('You typed a printable character.'); 

[SMG$K_TRM_PF1 TO SMG$K_TRM_PERIOD]: 

TTY_PUT_QUO ('You typed one of the keypad keys.'); 

[SMG$K_TRM_UP TO SMG$K_TRM_RIGHT]: 

TTY_PUT_QUO ('You typed one the cursor positioning keys.'); 
[SMG$K_TRM_F6 TO SMG$K_TRM_F20]: 

TTY.PUT.QUO ('You typed one of the function keys.'); 

[SMG$K_TRM_FIND TO SMG$K_TRM_NEXT.SCREEN]: 

TTY.PUT.QUO ('You typed one of the editing keys.'); 

[SMG$K_TRM_TIMEOUT]: 

TTY_PUT_QUO ('You did not type a key fast enough.'); 
[OTHERWISE]: 

TTY_PUT_QUO ('I am not sure what you typed.'); 

TES; 

TTY_PUT_CRLF (); 

! + 

! Terminate the Screen ManaGed connection to SYS$INPUT. 

i - 

SMG.STATUS = SMG$DELETE_VIRTUAL_KEYBOARD (KBID); 

CHECK (.SMG.STATUS); 

END; 

END 

ELUDOM 
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Example 3-4 illustrates the techniques used to call 
from VAX COBOL. 



SMG$READ_KEYSTROKE 


Example 3-4 Using SMG$ Procedures in VAX COBOL 


IDENTIFICATION DIVISION. 

PROGRAM-ID. KEYSTROKE. 

* 

* This routine creates a VIRTUAL DISPLAY and writes it to the PASTEBOARD. 

* Data is placed in the VIRTUAL DISPLAY via routine SMG$PUT.LINE. 

* SMG$READ_KEYSTROKE is called to read a key stroke from the VIRTUAL KEYBOARD. 

* 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 DISPLAY1 PIC 9(9) COMP. 

01 PASTE1 PIC 9(9) COMP. 

01 KEYBOARD1 PIC 9(9) COMP. 

01 ROWS PIC S9(9) COMP VALUE 7. 

01 COLUMNS PIC S9(9) COMP VALUE 60. 

01 DISPLAY.NAME PIC X(13) VALUE " DISPLAY ONE 
01 TERM.CHAR PIC 9(4) COMP. 

01 T.TEXT PIC X(6). 

01 TEXT.OUTPUT PIC X(24) VALUE " TERMINAL CHARACTER IS: 

01 PROMPT PIC X(2) VALUE "»" . 

01 LINE.l PIC X(12) VALUE "Hit any key.". 

01 LINE.2 PIC X(34) VALUE "This character will not be echoed.". 

01 LINE_3 PIC X(47) VALUE "The terminal character equivalent is displayed.". 

01 LINE.4 PIC X VALUE » ". 

01 THREE PIC S9(9) COMP VALUE 3. 

01 NINE PIC S9(9) COMP VALUE 9. 

01 SEVEN PIC S9(9) COMP VALUE 7. 

01 TWENTY_FIVE PIC S9(9) COMP VALUE 25. 

PROCEDURE DIVISION. 

PO. 

* Create the Virtual Display with a border. 

CALL "SMG$CREATE_VIRTUAL_DISPLAY" USING 
ROWS, COLUMNS, DISPLAY1. 

* Create the Pasteboard 

CALL "SMG$CREATE_PASTEBOARD" USING PASTE1. 

* Create a Virtual Keyboard 

CALL "SMG$CREATE_VIRTUAL_KEYBOARD" USING KEYBOARD1. 

* Paste the Virtual Display at row 3, column 9. 

CALL "SMG$LABEL_BORDER" USING DISPLAY1, BY DESCRIPTOR DISPLAY.NAME. 

CALL "SMG$PASTE_VIRTUAL_DISPLAY" USING 
DISPLAY1, PASTE1, THREE. NINE. 

* Place data in the Virtual Display 

CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE.l. 

CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE.2. 

CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE.3. 

CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE.4. 

* Read a key stroke from the Virtual Pasteboard. 

CALL "SMG$READ_KEYSTROKE" USING KEYBOARD1. TERM.CHAR, 

BY DESCRIPTOR PROMPT, OMITTED, BY REFERENCE DISPLAY1. 

CALL "SMG$PUT_LINE" USING DISPLAY1, BY DESCRIPTOR LINE.4. 

* Convert the decimal value of TERM.CHAR to a decimal ASCII text string. 

CALL "OTS$CVT_L_TI" USING TERM.CHAR, BY DESCRIPTOR T.TEXT. 

* Print out the decimal ASCII text string. 

CALL "SMGIPUT.LINE" USING DISPLAY1, BY DESCRIPTOR TEXT.OUTPUT. 

CALL "SMG$PUT_CHARS" USING DISPLAY1, BY DESCRIPTOR T.TEXT, 

BY REFERENCE SEVEN, TWENTY.FIVE. 

STOP RUN. 
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The FORTRAN program shown in Example 3-5 uses SMG$READ_ 
KEYSTROKE, as well as SMG$CREATE_VIRTUAL-DISPLAY, 
SMG$CREATE_PASTEBOARD, SMG$PASTE_VIRTUAL_DISPLAY, 
SMG$CREATE_VIRTUAL_KEYBOARD, and SMG$PUT_LINE. 

Example 3-5 Using SMG$ Procedures in VAX FORTRAN 


c+ 

C This routine creates a virtual display and writes it to the PASTEBOARD. 
C Data is placed in the virtual display via routine SMG$PUT_CHARS. 

C Include the SMG definitions. In particular, we want SMG$M_BORDER. 

C- 

INCLUDE '(ISMGDEF)' 

INTEGER SMG$CREATE_VIRTUAL_DISPLAY, SMG$CREATE_PASTEBOARD 
INTEGER SMG$PASTE_VIRTUAL_DISPLAY, 

1 SMG$CREATE_VIRTUAL_KEYBOARD 

INTEGER SMG$READ_KEYSTROKE, SMG$PUT_LINE 

INTEGER DISPLAY1, PASTE1, KEYBOARD1, ROWS. COLUMNS, 

1 TERM_CHAR 

CHARACTER*3 TEXT 
CHARACTER*27 TEXT-OUTPUT 
C+ 

C Create the virtual display with a border. 

C- 

ROWS = 7 
COLUMNS = 60 

ISTATUS = SMGICREATE-VIRTUAL.DISPLAY 
1 (ROWS, COLUMNS, DISPLAY1, SMG$M.BORDER) 

C+ 

C Create the pasteboard. 

C- 

ISTATUS = SMG$CREATE_PASTEBOARD (PASTED 
C+ 

C Create a virtual keyboard. 

C- 

ISTATUS = SMG$CREATE-VIRTUAL_KEYBOARD ( KEYBOARD1) 

C+ 

C Paste the virtual display at row 3, column 9. 

C- 


1 
1 
1 

C+ 

C Read 
C- 

1 

C+ 

C Convert the decimal value of TERM-CHAR to a decimal ASCII text string. 
C- 

ISTATUS = OTS$CVT-L_TI( TERM-CHAR, TEXT) 

TEXT-OUTPUT = ' TERMINAL CHARACTER IS: ' // TEXT 
C+ 

C Print the decimal ASCII text string. 

C- 

ISTATUS = SMG$PUT_LINE (DISPLAYi, TEXT-OUTPUT) 

ISTATUS = SMG$PUT_CHARS (DISPLAYI. TEXT, 7. 25) 

END 


ISTATUS = SMGIPASTE-VIRTUAL-DISPLAY ( DISPLAYI, PASTE1, 3, 9) 

ISTATUS = SMGIPUT-LINE (DISPLAYI, 

'Enter the character K after the » prompt.') 

ISTATUS = SMG$PUT_LINE (DISPLAYI. 

'This character will not be echoed as you type it.') 
ISTATUS = SMG$PUT_LINE (DISPLAYI, 

'The terminal character equivalent of K is displayed.') 
ISTATUS = SMGSPUT-LINE (DISPLAYI. ' ') 

a key stroke from the virtual pasteboard. 

ISTATUS = SMG$READ_KEYSTROKE ( KEYBOARD 1, TERM-CHAR, '»', . 
DISPLAYi) 

ISTATUS = SMG$PUT_LINE (DISPLAYi, ' ') 
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The VAX MACRO program shown in Example 3-6 demonstrates the precise 
steps required to call SMG$READ_KEYSTROKE from a low-level langauge. 

Example 3-6 Using SMG$ Procedures in VAX MACRO 


.TITLE SMG.DEMO 

; + 

; This program demonstrates the use of the SMG$ routines, in particular 
; SMG$READ_KEYSTROKE. 

$ 

IDSCDEF ; Declare DSC$ symbols 
$SMGDEF ; Declare SMG$ symbols 
;♦ 

; Declare external routines 

t 

.EXTRN SMGlCREATE.PASTEBOARD 
.EXTRN SMG$CREATE_VIRTUAL_DISPLAY 
.EXTRN SMG$CREATE_VIRTUAL_KEYBOARD 
.EXTRN SMGIPUT.LINE 
.EXTRN SMG$READ_KEYSTROKE 
;♦ 

; Declare data PSECT and objects 
• 

.PSECT $DATA RD,WRT,NOEXE,NOSHR,PIC 

LINE1: .ASCID "Enter the character K after the prompt." 

LINE2: .ASCID "This character will not be echoed as you type it." 

LINE3: .ASCID "The terminal character equivalent of K is displayed." 
PROMPT: .ASCID "»" 

BLANK: .ASCID " " 

FAOSTR: .ASCID "TERMINAL CHARACTER IS !UL" 

TEXT: .BLKB 80 ; Buffer for formatted text 
TEXT.LEN = . - TEXT ; Length of TEXT 
TEXT.DSC: ; Descriptor for TEXT string 
.WORD TEXT.LEN ; DSC$W_LENGTH 
.BYTE DSC$K_DTYPE_T ; DSC$B_DTYPE 
.BYTE DSC$K_CLASS_S ; DSC$B_CLASS 
.ADDRESS TEXT ; DSC$A_POINTER 

TERM.CHAR: 

.BLKL ; Space for terminator character code 
PASTEBOARD.1: 

.BLKL ; Pasteboard ID 
DISPLAY.l: 

.BLKL ; Display ID 
KEYBOARD.1: 

.BLKL ; Keyboard ID 


Declare PSECT for code. 

PSECT $C0DE RD,NOWRT,EXE,SHR,PIC 


(Continued on next page) 
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Example 3-6 (Cont.) Using SMG$ Procedures in VAX MACRO 


; + 

; Begin main routine. 

.ENTRY SMG.DEMO, ~M<> ; Save no registers 
; + 

; Create virtual display. 

PUSHL #SMG$M_BORDER ; Put flag on stack 

PUSHL #60 ; Put columns on stack 

PUSHL #7 ; Put rows on stack 

PUSHAB 8(SP) ; Address of flag 

PUSHAB L~DISPLAY_1 ; Address of display ID 

PUSHAB 12(SP) ; Address of columns 

PUSHAB 12(SP) ; Address of rows 

CALLS #4, G~SMG$CREATE_VIRTUAL_DISPLAY 

ADDL2 #12, SP ; Pop off temporaries 

; Create pasteboard. 

PUSHAB L~PASTEBOARD.1 ; Address of pasteboard 
CALLS #1, G ~ SMG$CREATE_PASTEBOARD 

; Create virtual keyboard. 

PUSHAB L~KEYBOARD.1 ; Address of keyboard 
CALLS #1, G~SMG$CREATE_VIRTUAL_KEYBOARD 

; Paste the virtual display at row 3, column 9. 

PUSHL #9 ; Put column on stack 

PUSHL #3 ; Put row on stack 

PUSHAB 4(SP) ; Address of column 

PUSHAB 4(SP) ; Address of row 

PUSHAB L~PASTEBOARD.1 ; Address of pasteboard 

PUSHAB L~DISPLAY_1 ; Address of display 

CALLS #4, G~SMG$PASTE_VIRTUAL_DISPLAY 

ADDL2 #8, SP ; Pop off temporaries 

; Write instructions. 

PUSHAB L~LINE1 ; "Enter the character..." 

PUSHAB L~DISPLAY.l ; Display ID 
CALLS #2, G~SMG$PUT_LINE 

PUSHAB L~LINE2 ; "This character will not..." 

PUSHAB L~DISPLAY_1 ; Display ID 
CALLS #2, G~SMG$PUT_LINE 

PUSHAB L~LINE3 ; "The terminal character..." 

PUSHAB L~DISPLAY_1 ; Display ID 
CALLS #2, G~SMG$PUT_LINE 
PUSHAB L"BLANK ; Blank line 
PUSHAB L"DISPLAY_1 ; Display ID 
CALLS #2, G~SMG$PUT_LINE 

; Read a keystroke from the virtual keyboard. 

PUSHAB L"DISPLAY_1 ; Display ID 
CLRL -(SP) ; No timeout 
PUSHAB L"PROMPT ; Prompt string 

PUSHAB L~TERM_CHAR ; Longword for terminator code 
PUSHAB L"KEYBOARD.1 ; Keyboard ID 
CALLS #5, G~SMG$READ_KEYSTROKE 

; Format the terminator code using $FA0. 

$FA0_S CTRSTR=L~FAOSTR,- ; FAO control string 
OUTLEN=L~TEXT_DSC+DSC$W_LENGTH,- ; Output string length 
0UTBUF=L~TEXT.DSC,- ; Output buffer 
P1=L"TERM.CHAR ; Value to format 


(Continued on next page) 
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Example 3-6 (Cont.) 


Using SMG$ Procedures in VAX MACRO 


; Display the formatted text. 

PUSHAB L"BLANK ; Blank line 
PUSHAB L~DISPLAY_1 ; Display ID 
CALLS #2, G~SMG$PUT_LINE 
PUSHAB L~TEXT_DSC ; Text to display 
PUSHAB L~DISPLAY_1 ; Display id 
CALLS #2, G~SMG$PUT_LINE 

; Return with status from last call. 

RET 

.END SMG_DEMO ; Specify SMG.DEMO as main program 
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Example 3-7 uses SMG$READ_KEYSTROKE from VAX PASCAL. It 
also demonstrates the use of SMG$CREATE_VIRTUAL_DISPLAY, 
SMG$CREATE_PASTEBOARD, SMG$CREATE_VIRTUAL_KEYBOARD, 
SMG$PASTE_VIRTUAL-DISPLAY, and SMG$PUT_LINE. 

Example 3-7 Using SMG$ procedures in VAX PASCAL 


{ This program demonstrates the use of the SMG$ routines, in particular > 
{ SMG$READ_KEYSTROKE. > 

[INHERIT('SYSILIBRARY:STARLET•)] 

PROGRAM SMG.DEMO; 

TYPE 

UNSIGNED.WORD = [WORD] 0..65535; 

FUNCTION SMG$CREATE_VIRTUAL_DISPLAY ( 

ROWS. COLUMNS: INTEGER; 

VAR DISPLAYED: INTEGER; 

DISPLAY.ATTRIBUTES, VIDEO.ATTRIBUTES, CHAR.SET: UNSIGNED 
:= '/.IMMED 0): UNSIGNED; EXTERN; 

FUNCTION SMG$CREATE_PASTEBOARD ( 

VAR PASTEBOARD.ID: INTEGER; 

OUTPUT.DEVICE: PACKED ARRAY [A..B:INTEGER] OF CHAR:= DIMMED 0; 

ROWS, COLUMNS: INTEGER := DIMMED 0; 

PRESERVE.SCREEN.FLAG: BOOLEAN := %IMMED 0): UNSIGNED; EXTERN; 

FUNCTION SMG$CREATE_VIRTUAL_KEYBOARD ( 

VAR KEYBOARD.ID: INTEGER; 

FILESPEC: PACKED ARRAY [A. .B: INTEGER] OF CHAR := '/.IMMED 0; 
DEFAULT.FILESPEC: PACKED ARRAY [C..D:INTEGER] OF CHAR := DIMMED 0; 
RESULTANT.FILESPEC: PACKED ARRAY [E..F:INTEGER] OF CHAR := DIMMED 0 
): UNSIGNED; EXTERN; 

FUNCTION SMG$PASTE.VIRTUAL_DISPLAY ( 

DISPLAYED, PASTEBOARD.ID: INTEGER; 

ROW, COLUMN: INTEGER): UNSIGNED; EXTERN; 

FUNCTION SMG$READ_KEYSTROKE ( 

KEYBOARD.ID: INTEGER; 

VAR TERMINATOR.CODE: UNSIGNED.WORD; 

PROMPT: PACKED ARRAY [A..B:INTEGER] OF CHAR := %IMMED 0; 

TIMEOUT, DISPLAY.ID: INTEGER := '/.IMMED 0): UNSIGNED; EXTERN; 

FUNCTION SMG$PUT_LINE ( 

DISPLAY.ID: INTEGER; 

TEXT: PACKED ARRAY [A..B:INTEGER] OF CHAR; 

LINE.ADVANCE: INTEGER := '/.IMMED 0; 

RENDITION.SET, RENDITION.COMPLEMENT: UNSIGNED := DIMMED 0; 

WRAP.FLAG: BOOLEAN := '/.IMMED 0; 

CHAR.SET: UNSIGNED := DIMMED 0): UNSIGNED; EXTERN; 

var 

PASTEBOARD.1, DISPLAY.l, KEYBOARD.1: INTEGER; 

TERMINATOR: UNSIGNED.WORD; 


(Continued on next page) 
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Example 3-7 (Cont.) Using SMG$ procedures in VAX PASCAL 


BEGIN 

i Create virtual display, pasteboard and virtual keyboard > 

SMG$CREATE_VIRTUAL_DISPLAY (ROWS := 7, COLUMNS := 60, 

DISPLAYED := DISPLAY.l. 

DISPLAY_ATTRIBUTES := SMGlM.BORDER); 

SMG$CREATE_PASTEBOARD (PASTEBOARD.ID := PASTEBOARD.1); 
SMGICREATE.VIRTUAL.KEYBOARD (KEYBOARD.ID := KEYBOARD.1); 

{ Paste the virtual display at row 3, column 9 > 

SMGlPASTE.VIRTUAL.DISPLAY (DISPLAY.ID := DISPLAY.l, 

PASTEBOARD.ID := PASTEBOARD.1, ROW := 3, COLUMN := 9); 

{ Write the instructions to the virtual display > 

SMGIPUT.LINE (DISPLAY.ID := DISPLAY.l, 

TEXT := 'Enter the character K after the » prompt.'); 
SMGIPUT.LINE (DISPLAY.ID := DISPLAY.l, 

TEXT :* 'This character will not be echoed as you type it.'); 
SMG$PUT_LINE (DISPLAY.ID := DISPLAY.l. 

TEXT := 'The terminal character equivalent of K is displayed.'); 
SMGIPUT.LINE (DISPLAY.ID := DISPLAY.l, 

TEXT :*''); 

{ Read the keystroke from the virtual keyboard > 

SMG$READ_KEYSTROKE (KEYBOARD.ID := KEYBOARD.1, 

DISPLAY.ID :* DISPLAY.l, 

TERMINATOR.CODE := TERMINATOR, PROMPT := '»'); 

{ Display the decimal value of the terminator code > 

SMGIPUT.LINE (DISPLAY.ID := DISPLAY.l. 

TEXT := ' '); 

SMGIPUT.LINE (DISPLAY.ID := DISPLAY.l, 

TEXT := 'TERMINAL CHARACTER IS ' + DEC(TERMINATOR,5.1)); 

END. 
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The program shown in Example 3-8 calls SMG$READ_KEYSTROKE from 
VAX PL/I. 

Example 3-8 Using SMG$ Procedures in VAX PL/I 


/* 

* Example of SMG$READ_KEYSTROKE. 

*/ 

/* 

* Declare the RTL entry points. 

*/ 

declare 

SMG$CREATE_VIRTUAL_KEYBOARD external entry( 
fixed binary(31), /* new-keyboard-id */ 
character(*), /* filespec */ 
character(*), /* default-filespec */ 
character(*) varying ) /* resultant-filespec */ 
returns(fixed binary(31)) options(variable); 
declare 

SMG$DELETE_VIRTUAL_KEYBOARD external entry( 
fixed binary(31) ) /* keyboard-id */ 
retnms(fixed binary(31)); 
declare 

SMG$READ_KEYSTROKE external entry( 
fixed binary(31), /* keyboard-id */ 
fixed binary(15), /* terminator-code */ 
character(*), /* prompt-string */ 
fixed binary(31), /* timeout */ 
fixed binsiry(31) ) /* display-id */ 
return8(fixed binary(31)) options(variable); 

/* 

* Get the value of the SMG constants from PLISTARLET. 

*/ 

'/.include ISMGDEF; 

declare SMG$_EOF globalref value fixed binary(31); 

/* 

* Misc. constants. 

*/ 

^replace false by 'O'b; 
y,replace true by 'l'b; 

/* 

* The following compile-time procedure will signal an error at run-time 

* if the status value that it is passed does not have success or 

* informational severity. (i.e. if the low bit is not set.) 

*/ 

*/,signal_if: procedure (status.val) returns (character) ; 
y,declare status_val character; 

y,retum( 'if posintC I I status.val I I ' ,1,1) ■ 0 ' II 
'then signal vaxcondition(' I I status_val I I ')' ); 

%end; 

main: proc options(main, ident('V4.2')); 
declare exit bit initial(false); 
declare status fixed binary(31); 
declare keyboard.id fixed binary(31); 
declare terminator fixed binary(15); 

/* 

* Create the virtual keyboard necessary for the read. 

*/ 

status * smg$create_virtual_keyboard( keyboard.id ); 
signal_if( status ); 


(Continued on next page) 
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Example 3-8 (Cont.) Using SMG$ Procedures in VAX PL/I 


/* 

* Read a single keystroke. If that keystroke is an end-of-file, 

* then exit. Otherwise, SELECT the appropriate action based on 

* the key. 

*/ 

do while(“exit); 

status = smg$read_keystroke( keyboard.id, terminator, 

'Command: ', 20 ); 
if status = SMG$_E0F 
then exit = true; 
else do; 

signal.if( status ); 
select (terminator); 

when (SMG$K_TRM_PF2, 

SMG$K_TRM_HELP, 
rank('H'), 
rank('h'), 

rank('?') ) call display_help; 

when(SMG$K.TRM_D0) call do.command; 

when(rank('E'), 
rank('e')) exit = true; 

otherwise call command.error; 
end; 

end; 

end; 

/* 

* We're done, so delete the virtual keyboard. 

*/ 

status = 8mg$delete_virtual_keyboard( keyboard.id ); 

8ignal_if( status ); 

end main; 

display.help: procedure; 

put skip edit('This program uses single keystroke commands.') (A); 
put skip edit('The following keys sure valid:') (A); 
put skip; 

put skip editO Key Function') (A); 

put skip edit(' E/e Exit') (A) ; 

put skip editC <D0> Your choice...') (A); 

put skip edit(' ?/H/h/<HELP> Help') (A); 

put skip; 

end display.help; 


(Continued on next page) 
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Example 3-8 (Cont.) Using SMG$ Procedures in VAX PL/I 


do_command: procedure; 

put skip edit('The DO key was pressed') (A); 
put skip; 
end do.command; 
command.error: procedure; 

put skip edit('The key pressed was not valid - please try again.') (A); 
put skip edit('(H for HELP).' ) (A); 
put skip; 

end command.error; 
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Example 3-9 demonstrates how to call SMG$READ_KEYSTROKE from VAX 
RPG II. This program also uses SMG$CREATE_VIRTUAI^.KEYBOARD and 
SMG$DELETE_VIRTUAL_KEYBOARD. 

Example 3-9 Using SMG$ Procedures in VAX RPG II 


0I1I2I3I4I5I6I7I 

12345078901234567890123456789012345678901234567890123456789012345678901234567890 


F*+ 


F* This RPG II program demonstrates the use of the RTL routine 
F* SMG$READ_KEYSTROKE to read a keystroke from the terminal. 

F* 

F* The program takes input from the terminal until CTRL/Z is typed. 
F* If any of the four cursor positioning keys is typed, a string 
F* is displayed corresponding to the key. 

F* 

F* Build this program using the following commands: 

F* 

F* $ RPG READ.KEY 
F* $ CREATE SMGDEF.MAR 

F* .TITLE SMGDEF - Define SMG$ constants 

F* .Ident /1-000/ 

F* 

F* $SMGDEF GLOBAL 

F* .END 

F* $ MACRO SMGDEF 

F* $ LINK READ.KEY,SMGDEF 

F*- 


FTTY D V 5 


TTY 


C* 

C 

C 

C 

C* 

C 

C 

C 

C 

C 


External definitions for SMG routines. 

CREKB EXTRN'SMG$CREATE_VIRTUAL_KEYBOARD' 

DELKB EXTRN'SMG$DELETE_VIRTUAL_KEYBOARD' 

REAKEY EXTRN'SMG$READ_KEYSTROKE' 

External definitions for SMG terminators. 

T_UP EXTRN'SMG$K_TRM_UP• 

T.DOWN EXTRN'SMG$K_TRM_DOWN' 

T.LEFT EXTRN'SMG$K_TRM_LEFT' 

T_RIGHT EXTRN'SMG$K_TRM_RIGHT• 

T_CTRLZ EXTRN'SMG$K_TRM_CTRLZ' 


C* 

C 

C 

C 

C* 

C 

C 

C 

C* 


Create the virtual keyboard. 


N99 


Read 


Turn 


CALL CREKB 




PARM 

KB_ID 

90 

WL 

SETON 



99 

keystroke. 




CALL REAKEY 




PARM 

KB.ID 

90 

RL 

PARM 

T.CODE 

50 

WW 

l an indicator if a cursor 

positioning 

key was typed 


C 


T.CODE 

COMP T.UP 

01 

C 


T.CODE 

COMP T.DOWN 

02 

C 


T.CODE 

COMP T.LEFT 

03 

C 


T.CODE 

COMP T.RIGHT 

04 

C* 

Turn on 

LR to quit 

if CTRL/Z was typed. 


C 


T.CODE 

COMP T.CTRLZ 

LR 

C* 

Display 

a message 

if a cursor positioning key 

was typed 

C 

01 

•UP' 

DSPLYTTY 


C 

02 

•DOWN' 

DSPLYTTY 


C 

03 

•LEFT' 

DSPLYTTY 


C 

04 

•RIGHT' 

DSPLYTTY 



C* Delete the virtual keyboard. 

CLR CALL DELKB 

CLR PARM KB.ID 90 RL 
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The RPG II program above displays the following: 

UP 

DOWN 

RIGHT 

LEFT 

if the cursor positioning and control keys are typed. These keys include the 
arrow keys (up, down, right, and left) and CTRL/Z. 
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4 


Introduction to Mathematics Procedures 




4.1 



The Run-Time Library mathematics procedures may be called to perform a 
wide variety of computations including the following: 

• Complex exponentiation 

• Complex function evaluation 

• Exponentiation 

• Floating-point trigonometric function evaluation 

• Miscellaneous function evaluation 

The OTS$ facility provides additional language-independent arithmetic 
support procedures. 

This introduction to Run-Time Library mathematics procedures includes 
examples of how to call mathematics procedures from BASIC, COBOL, 
FORTRAN, MACRO, PASCAL, and PL/I. 


Entry Point Names 

The names of the mathematics procedures are formed by adding the MTH$ 
prefix to the function names. 

When function arguments and returned values are the same data type, the 
first letter of the name indicates this data type. When function arguments 
and returned values are different data types, the first letter indicates the data 
type of the returned value, and the second letter indicates the data type of 
the argument(s). 

The letters used as data type prefixes are listed below. 


Letter 

Data Type 

1 

Word 

J 

Longword 

D 

D_floating 

G 

G_floating 

H 

H_floating 

C 

F_floating complex 

CD 

D_floating complex 

CG 

G floating complex 


Generally, F_floating data types have no letter designation. For example, 
MTH$SIN returns an F_floating value of the sine of an F__floating argument 
and MTH$DSIN returns a D__floating value of the sine of a D_floating 
argument. However, in some of the miscellaneous functions, F_floating data 
types are referenced by the letter designation A. 
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4.2 Calling Conventions 

All calls to mathematics procedures, which are described in the FORMAT 
section of each procedure, accept arguments passed by reference. JSB entry 
points accept arguments passed by value. 

All mathematics procedures return values in RO or R0/R1 except those 
procedures for which the values cannot fit in 64 bits. D_floating complex, 
G—floating complex and H_floating values are data structures which are 
larger than 64 bits. Procedures that return values which cannot fit in R0/R1 
return their function values into the first argument in the argument list. 

The notation JSB MTH$NAME_Rn, where n is the highest register number 
referenced, indicates that an equivalent JSB entry point is available. No 
registers are saved; only registers R0:Rn are changed. 

Procedures with JSB entry points accept a single argument in R0:Rm, where 
m, which is defined below, is dependent on the data type. 


Data Type 

m 

F_floating 

0 

D_floating 

1 

G_floating 

1 

H_floating 

3 


A procedure which returns one value returns it to registers R0:Rm. 

When a procedure returns two values, for example MTH$SINCOS, the 
first value is returned in R0:Rm and the second value is returned in 
(R <m+l> :R <2*m+l> ). 

Note that for procedures that return a single value, n> =m. For procedures 
that return two values, n> =2*m + 1. 

All CALL entry points for mathematics procedures do the following: 

• Disable floating-point underflow 

• Enable integer overflow 

• Cause no floating-point overflow or other arithmetic traps or faults 

• Preserve all other enabled operations across the CALL 

JSB entry points execute in the context of the caller with the enable operations 
as set by the caller. Since the procedures do not cause arithmetic traps or 
faults, their operation is not affected by the setting of the arithmetic trap 
enables, except as noted. 

See Section 2 for more detailed information on CALL and JSB entry points. 


4.3 Algorithms 

For those mathematics procedures that have corresponding algorithms, the 
complete algorithm can be found in the Description section of the routine 
description appearing in Part II of this manual. 
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4.4 Condition Handling 

Error conditions are indicated by using the VAX signaling mechanism. The 
VAX signaling mechanism signals all conditions in mathematics procedures 
as SEVERE by calling LIB$SIGNAL. When a SEVERE error is signaled, the 
image is caused to exit after printing an error message. A user-established 
condition handler can be written to cause execution to continue at the point of 
the error by returning SS$_CONTINUE. A mathematics procedure returns to 
its caller after the contents of R0/R1 have been restored from the mechanism 
argument vector CHF$L_MCH_SAVR0/R1. Thus, the user-established 
handler should correct CHF$L_MCH_SAVR0/R1 to the desired function 
value to be returned to the caller of the mathematics procedure. 

D_floating complex, G_floating complex, and H_floating values cannot be 
corrected with a user-established condition handler, because R2/R3 are not 
available in the mechanism argument vector. 

Note that it is more reliable to correct RO and R1 to resemble RO and R1 of 
a double-precision floating-point value. A double-precision floating-point 
value correction works for both single- and double-precision values. If the 
correction is not performed, the floating-point reserved operand -0.0 is 
returned. A floating-point reserved operand is a floating-point datum with 
a sign bit of 1 and a biased exponent of zero. Accessing the floating-point 
reserved operand will cause a reserved operand fault. See Section 7 for a 
complete description of how to write user condition handlers for SEVERE 
errors. 

A few mathematics procedures signal floating underflow if the calling 
program (JSB or CALL) has enabled floating underflow faults or traps. 

All mathematics procedures access input arguments and the real and 
imaginary parts of complex numbers using floating-point instructions. 
Therefore, a reserved operand fault can occur in any mathematics procedure. 


4.5 Complex Numbers 

A complex number y is defined as an ordered pair of real numbers r and i, 
where r is the real part and i is the imaginary part of the complex number. 

y=(r,i) 

VAX/VMS supports three floating-point complex types: F_floating complex, 
D_floating complex, and G_floating complex. There is no H_floating 
complex data type. 

Run-Time Library mathematics procedures that use complex arguments 
require two x_floating values to be passed by reference for each argument. 
The first x_floating value contains r, the real part of the complex number. 
The second x__floating value contains i, the imaginary part of the complex 
number. Similarly, Run-Time Library mathematics procedures that return 
complex function values return two x__floating values. Some Language 
Independent Support (OTS$) procedures also calculate complex functions. 

Note that complex functions have no JSB entry points. 
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4.6 


Mathematics Procedures Not Documented in Template Format 

The mathematics procedures in Table 4-1 are not found in routine templates 
in Part II of this manual. See the Summary of Run-Time Library Entry 
Points, Appendix G for the CALL and corresponding JSB entry points for 
these procedures. 

A reserved operand fault can occur for any floating-point input argument 
in any mathematics procedure. Other condition values signaled by each 
mathematics procedure are indicated in the footnotes. 


Table 4-1 Additional Mathematics Procedures 


Entry Point 

MTH$ABS 

MTHSDABS 

MTHSGABS 

MTH$HABS 

MTH$IIABS 

MTH$JIABS 

MTH$IIAND 

MTH$JIAND 

MTH$DBLE 

MTH$GDBLE 

MTH$DIM 

MTH$DDIM 

MTHSGDIM 

MTHSHDIM 

MTH$IIDIM 

MTH$JIDIM 

MTHSIIEOR 

MTH$JIEOR 

MTHSIIFIX 

MTHSJIFIX 


Function 

F_floating absolute value 

D_floating absolute value 

G_floating absolute value 

H_floating absolute value 1 

Word absolute value 2 

Longword absolute value 2 

Bitwise AND of two word arguments 

Bitwise AND of two longword arguments 

Convert F_floating to D_floating (exact) 

Convert F_floating to G_floating (exact) 

Positive difference of two F_floating arguments 3 ’ 4 
Positive difference of two D_floating arguments 3 ’ 4 
Positive difference of two G_floating arguments 3 ’ 4 
Positive difference of two H_floating arguments 1 ’ 3 ’ 4 
Positive difference of two word arguments 2 
Positive difference of two longword arguments 2 
Bitwise exclusive OR of two word arguments 
Bitwise exclusive OR of two longword arguments 
Convert F_floating to word (truncated) 2 
Convert F_floating to longword (truncated) 2 


Returns value to the first argument; value exceeds 64 bits. 
2 lnteger overflow exceptions can occur. 

3 Floating-point overflow exceptions can occur. 
4 Floating-point underflow exceptions can occur. 
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Table 4—1 (Cont.) Additional Mathematics Procedures 

Entry Point Function 


MTHSFLOATI 

MTH$DFLOTI 

MTH$GFLOTI 

MTH$FLOATJ 

MTHSDFLOTJ 

MTHSGFLOTJ 

MTH$FLOOR 

MTH$DFLOOR 

MTH$GFLOOR 

MTHSHFLOOR 

MTH$AINT 

MTH$DINT 

MTHSIIDINT 

MTHSJIDINT 

MTHSGINT 

MTH$IIGINT 

MTH$JIGINT 

MTH$HINT 

MTH$IIHINT 

MTH$JIHINT 

MTH$IINT 

MTH$JINT 

MTHSIIOR 

MTH$JIOR 

MTHSAIMAXO 

MTHSAJMAXO 

MTH$IMAXO 

MTH$JMAXO 

MTH$AMAX1 


Convert word to F_floating (exact) 

Convert word to D_floating (exact) 

Convert word to G_floating (exact) 

Convert longword to F_floating (exact) 

Convert word to D_floating (exact) 

Convert longword to G_floating (exact) 

Convert F_floating to greatest F_floating integer 
Convert D_floating to greatest D_floating integer 
Convert G_floating to greatest G_floating integer 
Convert H_floating to greatest H_floating integer 1 
Convert F_floating to truncated F_floating 3 
Convert D_floating to truncated D_floating 
Convert D_floating to word (truncated) 2 
Convert D_floating to longword (truncated) 2 
Convert G_floating to G_floating (truncated) 
Convert G_floating to word (truncated) 2 
Convert G_floating to longword (truncated) 2 
Convert H_floating to H_floating (truncated) 1 ’ 3 
Convert H_floating to truncated word 2 
Convert H_floating to truncated longword 2 
Convert F_floating to word (truncated) 2 
Convert F_floating to longword (truncated) 2 
Bitwise inclusive OR of two word arguments 
Bitwise inclusive OR of two longword arguments 
F_floating maximum of n word arguments 
F_floating maximum of n longword arguments 
Word maximum of n word arguments 
Longword maximum of n longword arguments 
F_floating maximum of n F_floating arguments 2 


Returns value to the first argument; value exceeds 64 bits. 
2 lnteger overflow exceptions can occur. 

3 Floating-point overflow exceptions can occur. 
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Table 4-1 (Cont.) Additional Mathematics Procedures 


Entry Point 

MTH$DMAX1 

MTH$GMAX1 

MTH$HMAX1 

MTH$IMAX1 

MTH$JMAX1 

MTHSAIMINO 

MTHSAJMINO 

MTH$IMINO 

MTH$JMINO 

MTH$AMIN1 

MTH$DMIN1 

MTH$GMIN1 

MTH$HMIN1 

MTH$IMIN1 

MTH$JMIN1 

MTH$AMOD 

MTH$DMOD 

MTH$GMOD 

MTHSHMOD 

MTHSIMOD 

MTHSJMOD 

MTHSANINT 

MTH$DNINT 

MTH$IIDNNT 

MTHSJIDNNT 

MTHSGNINT 

MTHSIIGNNT 


Function 

D_floating maximum of n D_floating arguments 
G_floating maximum of n G_floating arguments 
H_floating maximum of n H_floating arguments 1 
Word maximum of n F_floating arguments 2 
Longword maximum of n F_floating arguments 2 
F_floating minimum of n word arguments 
F_floating Minimum of n longword arguments 
Word minimum of n word arguments 
Longword minimum of n longword arguments 
F_floating minimum of n F_floating arguments 2 
D_floating minimum of n D_floating arguments 
G_floating minimum of n G_floating arguments 
FLfloating minimum of n H_floating arguments 1 
Word minimum of n F_floating arguments 2 
Longword minimum of n F_floating arguments 2 
Remainder of two F_floating arguments, arg1/arg2 3 
Remainder of two D_floating arguments, arg1/arg2 3 
Remainder of two G_floating arguments, arg1/arg2 3 
Remainder of two FI_floating arguments, arg1/arg2 1 ’ 3 
Remainder of two word arguments, arg1/arg2 5 
Remainder of two longword arguments, arg1/arg2 5 
Convert F_floating to nearest F_floating integer 
Convert D_floating to nearest D_floating integer 3 
Convert D_floating to nearest word integer 
Convert D_floating to nearest longword integer 
Convert G_floating to nearest G_floating integer 3 
Convert G_floating to nearest word integer 2 


Returns value to the first argument; value exceeds 64 bits. 
2 lnteger overflow exceptions can occur. 

3 Floating-point overflow exceptions can occur. 

5 Divide-by-zero exceptions can occur. 
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Table 4-1 (Cont.) Additional Mathematics Procedures 


Entry Point 

Function 

MTH$JIGNNT 

MTH$HNINT 

MTHSIIHNNT 

MTHSJIHNNT 

MTHSININT 

MTH$JNINT 

MTHSINOT 

MTHSJNOT 

MTHSDPROD 

MTH$GPROD 

MTH$SGN 

MTH$SGN 

MTHSIISHFT 

MTH$JISHFT 

MTHSSIGN 

MTH$DSIGN 

MTH$GSIGN 

MTHSHSIGN 

MTHSIISIGN 

MTHSJISIGN 

MTH$SNGL 

MTH$SNGLG 

Convert G_floating to nearest longword integer 2 

Convert H_floating to nearest H_floating integer 1 

Convert H_floating to nearest word integer 2 

Convert H_floating to nearest longword integer 2 

Convert F_floating to nearest word integer 2 

Convert F_floating to nearest longword integer 3 ’ 6 

Bitwise complement of word argument 

Bitwise complement of longword argument 

D_floating product of two F_floating arguments 3 

G_floating product of two F_floating arguments 3 

F_Floating sign function 

D_floating sign function 

Bitwise shift of word 

Bitwise shift of longword 

F_floating transfer of sign of y to sign of x 

D_floating transfer of sign of y to sign of x 

G_floating transfer of sign of y to sign of x 

H_floating transfer of sign of y to sign of x 1 

Word transfer of sign of y to sign of x 

Longword transfer of sign of y to sign of x 

Convert D_floating to F_floating (rounded) 3 

Convert G_floating to F_floating (rounded) 3 4 


Returns value to the first argument; value exceeds 64 bits. 
2 lnteger overflow exceptions can occur. 

3 Floating-point overflow exceptions can occur. 
4 Floating-point underflow exceptions can occur. 

6 Returns contents of RO if a negative argument is input. 
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4.7 Examples of Calls to Run-Time Library Mathematics 
Procedures 


4.7.1 BASIC Example 

The following BASIC program uses the H_floating data type. BASIC also 
supports the D_floating, F_floating and G—floating data types, but does not 
support the complex data types. 

10 ! + 

! Sample program to demonstrate a call to MTH$HEXP from BASIC. 

! - 

EXTERNAL SUB MTH$HEXP ( HFLOAT, HFLOAT ) 

DECLARE HFLOAT X.Y ! X and Y are H.floating 

DIGITS! = '###.#################################' 

X = 1 1.2345678901234567891234567892'H 
CALL MTH$HEXP (Y.X) 

A$ = 'MTHIHEXP of ' + DIGITS! + ' is ' + DIGITS! 

PRINT USING A!, X, Y 
END 


output: 

MTH!HEXP of 1.234567890123456789123456789200000 
is 3.436893084346008004973301321342110 


4.7.2 COBOL Example 

The following COBOL program uses the F_Jloating and D__floating data 
types. COBOL does not support the G_floating and PL_floating data types or 
the complex data types. 

This COBOL program calls MTH$EXP and MTH$DEXP. 


IDENTIFICATION DIVISION. 

PROGRAM-ID. FLOATING-POINT. 

* 

* Calls MTH!EXP using a Floating Point data type. 

* Calls MTH!DEXP using a Double Floating Point data type. 

* 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 FLOAT.PT COMP-1. 

01 ANSWER.F COMP-1. 

01 DOUBLE.PT COMP-2. 

01 ANSWER.D COMP-2. 

PROCEDURE DIVISION. 

PO. 

MOVE 12.34 TO FLOAT.PT. 

MOVE 3.456 TO DOUBLE.PT. 


CALL "MTH!EXP" USING BY REFERENCE FLOAT.PT GIVING ANSWER.F. 
DISPLAY M MTH!EXP of ", FLOAT.PT CONVERSION, " is ", 

ANSWER.F CONVERSION. 


CALL "MTH!DEXP" USING BY REFERENCE DOUBLE.PT GIVING ANSWER.D. 
DISPLAY " MTH!DEXP of ", DOUBLE.PT CONVERSION, " is ", 

ANSWER.D CONVERSION . 


STOP RUN. 
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output: 

MTH$EXP of 1.234000E+01 is 2.286620E+05 
MTH$DEXP of 3.456000000000000E+00 is 
3.168996280537917E+01 


4.7.3 FORTRAN Examples 

The first two FORTRAN programs below use the D_floating and H_floating 
data types. The third FORTRAN program below uses the F_iloating complex 
data type. FORTRAN supports the four floating data types and the three 
complex data types. 


Q c+ 

C This FORTRAN program computes exp(x) in 

C double precision by using the RTL routine " MTH$DEXP x ". 

C 

C Declare X,Y and MTH$DEXP as double precision values. 

C MTH$DEXP(X) will return a double precision value to variable Y. 
C- 

REAL*8 X, Y,MTH$DEXP 
X = 3.456 
Y = MTH$DEXP(X) 

WRITE(6,1) X,Y 

1 FORMAT( 1 ' , 'MTHlDEXPO .F20.15, ') IS \F20.15) 

END 


output: 

MTH$DEXP(3.456000000000000) IS 
31.689962805379165 


C This FORTRAN program computes exp(x) using 
C the RTL routine MTH$HEXP. MTH$HEXP is CALLed by 
C MTH$HEXP(return.value , argument) 

C 

C Declare X,Y as H.floating point values. 

C Given X MTH$HEXP will return the value of exp(X) in Y by the call 
C CALL MTH$HEXP(Y,X). 

C- 

REAL*16 X,Y 

X = 1.2345678901234567891234567892 
CALL MTH$HEXP(Y,X) 

WRITE(6,1) X,Y 

1 FORMAT(' ',•MTH$HEXP of ',£35.30,' is '.E35.30) 

END 


output: 

MTH$HEXP of .123456789012345678912345678920E+01 
is .343689308434600800497330132134E+01 
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0 C 

c+ 

C This FORTRAN program computes the complex log 

C of x using the RTL routine MTH$CL0G. This program also demonstrates 
C two ways the user can create a complex number. 

C 

C Declare Z,Z_L0G,MTH$CMPLX, and MTH$CLOG as complex values and R and I 
C as real values. MTH$CMPLX takes two real arguments and returns one 
C complex number: Z = MTH$CMPLX(R,I) is a complex number with "real" 

C part R and "imaginary" part I. 

C 

C Given a complex number Z, MTH$CLOG(Z) returns the complex natural 
C logarithm of Z. 

C- 

COMPLEX Z,Z_LOG,MTH$CMPLX,MTH$CLOG 
REAL*4 R.I 
R = 3.142563 
I * 7.4367846 
Z = MTH$CMPLX(R.I) 

C+ 

C Z is a complex number with real part R and imaginary part I. 

C- 

TYPE *, ' The complex number z is'.z 
C+ 

C Compute the natural logarithm of Z = (2,1). 

C Directly define the complex number Z. 

C- 

Z = (2.0,1.0) 

Z.LOG = MTH$CL0G(Z) 

TYPE The complex log of (2,1) is ',Z.LOG 
END 


output: 

The complex number z is (3.142563,7.436785) 
The complex log of (2,1) is 
(0.8047190,0.4636476) 


4.7.4 MACRO Examples 

MACRO and BLISS support JSB entry points as well as CALLS and CALLG 
entry points. Both MACRO and BLISS support the four floating data types 
and the three complex data types. 

The MACRO programs below illustrate the use of the CALLS and CALLG 
instructions, as well as JSB entry points. 

Q .TITLE EXAMPLE.JSB 

; + 

; This example calls MTH$DEXP by using a Macro JSB command. 

; The JSB command expects R0/R1 to contain the quadword input value X. 

; The result of the JSB will be located in R0/R1. 

.EXTRN MTH$DEXP_R6 ;MTH$DEXP is an external routine. 

.PSECT DATA, PIC, EXE, N0WRT 
X: .DOUBLE 2.0 ; X is 2.0 

.ENTRY EXAMPLE.JSB, *M<> 

M0VQ X, R0 ; X is in registers R0 and R1 

JSB G~MTH$DEXP_R6 ; The result is returned in R0/R1. 

RET 

.END EXAMPLE.JSB 
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output: 

RO <-- 732541EC 
R1 <-- ED6EC6A6 

That is, MTH$DEXP(2) is 7.3890560989306502 


.TITLE EXAMPLE.CALLG 


This example calls MTH$HEXP by using a Macro CALLG command. 

The CALLG command expects that the address of the return value 
Y, the address of the input value X, and the argument count 2 be 
stored in memory; this program stores this information in ARGUMENTS. 
The result of the CALLG will be located in R0/R1. 


.EXTRN MTHIHEXP 
.PSECT DATA, PIC, 
ARGUMENTS: 

.LONG 2 
.ADDRESS Y, X 


X: .H.FLOATING 2 

Y: .H.FLOATING 0 

.ENTRY EXAMPLE.G. 
CALLG ARGUMENTS, 
RET 

.END EXAMPLE.G 


; MTH$HEXP is an external routine. 

EXE, WRT 

; The CALLG will use two arguments. 

; The first argument must be the address 
; receiving the computed value, while 
; the second argument is used to 
; compute exp(X). 

; X = 2.0 

; Y is the result, initially set to 0. 

~M<> 

G~MTH$HEXP ; CALLG returns the value to Y. 


output: 


address of Y <-- 
<-- 
<-- 
<-- 


D8E64003 

4DDA4B8D 

3A3BDCC3 

B68BA206 


That is, MTH$HEXP of 2.0 returns 
7.38905609893065022723042746057501 


.TITLE EXAMPLE.CALLS 


This example calls MTH$HEXP by using the Macro CALLS command. 

The CALLS command expects the SP to contain the H.floating address of 
the return value, the address of the input argument X and the argument 
count 2. The result of the CALLS will be located in registers R0-R3. 


Y: 

X: 


.EXTRN 

MTHIHEXP 

; MTH$HEXP is an external routine. 

.PSECT 

DATA, PIC, EXE, 

WRT 

.H.FLOATING 0 

; Y is the result, initially set to 0. 

.H.FLOATING 2 

; X = 2 

.ENTRY 

EXAMPLE.S, *M<> 


MOVAL 

X. -(SP) 

; The address of X is in the SP. 

MOVAL 

Y, -(SP) 

; The address of Y is in the SP 

CALLS 

Y, G~MTH$HEXP 

; The value is returned to the address of Y 

RET 



.END 

EXAMPLE.S 



output: 


address of Y <-- 
<-- 


<-- 


D8E64003 

4DDA4B8D 

3A3BDCC3 

B68BA206 


That is, MTH$HEXP of 2.0 returns 
7.38905609893065022723042746057501 
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Q .TITLE C0MPLEX.EX1 


This example calls MTH$CL0G by using a MACRO CALLG command. 

To compute the complex natural logarithm of Z = (2.0,1.0) register 

R0 is loaded with 2.0, the real part of Z, and register R1 is loaded 

with 1.0, the imaginary part of Z. The CALLG to MTH$CL0G 

returns the value of the natural logarithm of Z in 

registers R0 and R1. R0 gets the real part of Z and R1 

gets the imaginary part. 


ARCS: 


.EXTRN MTHICLOG 
.PSECT DATA, PIC, EXE, 
.LONG 1 
.ADDRESS REAL 


NOWRT 

; The CALLG will use one argument. 

; The one argument that the CALLG 
; uses is the address of the argument 
; of MTH$CL0G. 


REAL: 

IMAG: 


.FLOAT 2 ; 

.FLOAT 1 ; 
.ENTRY C0MPLEX.EX1, “MO 
CALLG ARGS. G“MTH|CL0G; 


the imaginary part in R1. 
RET 

.END C0MPLEX.EX1 


real part of Z is 2.0 
imaginary part Z is 1.0 

MTHICLOG return the real part of the 
complex natural logarithm in RO and 


output: 

RO <--- 0210404E 

R1 <--- 63383FED 

That is, MTHICLOG(2.0,1.0) is 
(0.8047190,0.4636476) 

E .TITLE C0MPLEX.EX2 

; + 

; This example calls MTHICLOG by using a MACRO CALLS command. 

; To compute the complex natural logarithm of Z = (2.0,1.0) register 
; RO is loaded with 2.0, the real part of Z, and register R1 is loaded 

; with 1.0, the imaginary part of Z. The CALLS to MTHICLOG 

; returns the value of the natural logarithm of Z in registers RO 

; and R1. RO gets the real part of Z and R1 gets the imaginary 

; part. 



.EXTRN 
.PSECT 

MTHICLOG 

DATA. PIC, EXE, 

NOWRT 

REAL: 

.FLOAT 

2 

; real part of Z is 2.0 

IMAG: 

.FLOAT 

1 

; imaginary part Z is 1.0 


.ENTRY 

C0MPLEX.EX2, “MO 


MOVAL 

REAL. -(SP) 

; SP <-- address of Z. Real part of Z is 


CALLS 

#1, G“MTHICLOG 

; in <D(SP) and imaginary part is in 
; <8(SP)+4. 


MTHICLOG return the real part of the 
complex natural logarithm in RO and 
the imaginary part in R1. 


RET 

.END C0MPLEX.EX2 


output: 

RO <--- 0210404E 

R1 <--- 63383FED 

That is. MTHICLOG(2.0,1.0) is 
(0.8047190.0.4636476) 
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4.7.5 PASCAL Examples 

The following PASCAL programs use the D_floating and H__floating data 
types. PASCAL also supports the F_floating and G_floating data types. 
PASCAL does not support the complex data types, however. 

□ {♦> 

{ Sample program to demonstrate a call to MTH$DEXP from PASCAL. 

{-> 

PROGRAM CALL_MTH$DEXP (OUTPUT); 

{+> 

{ Declare variables used by this program. 

<-> 

VAR 

X : DOUBLE := 3.456; { X,Y are D_floating unless overridden > 

Y : DOUBLE; •( with /DOUBLE qualifier on compilation > 

{+> 

{ Declare the RTL routine used by this program. 

<-> 

[EXTERNAL.ASYNCHRONOUS] FUNCTION MTH$DEXP (VAR value : DOUBLE) : DOUBLE; EXTERN; 

BEGIN 

Y := MTH$DEXP (x); 

WRITELN CMTH$DEXP of '. X:5:3, ' is ', Y:20:16); 

END. 


output: 

MTHIDEXP of 3.456 is 31.6899656462382318 


B {+> 

{ Sample program to demonstrate a call to MTH$HEXP from PASCAL. 

{-> 

PROGRAM CALL_MTH$HEXP (OUTPUT); 

{♦} 

{ Declare variables used by this program. 

<-> 

VAR 

X : QUADRUPLE := 1.2345678901234567891234567892; { X is H.floating > 
Y : QUADRUPLE; { Y is H.floating > 

<+> 

■{ Declare the RTL routine used by this program. 

{-} 

[EXTERNAL,ASYNCHRONOUS] PROCEDURE MTH$HEXP (VAR h.exp : QUADRUPLE; 
value : QUADRUPLE); EXTERN; 

BEGIN 

MTH$HEXP (Y.X); 

WRITELN ('MTH$HEXP of X:30:28, ' is Y.35:33); 

END. 


output: 

MTH$DEXP of 3.456 is 31.6899656462382318 
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4.7.6 PL/I Examples 


The following PL/I programs use the D_floating and H_floating data types 
to test entry points. PL/I also supports the F_floating and G_floating data 
types. PL/I does not support the complex data types, however. 


□ 


* This program tests a MTH$D entry point 

* 

*/ 

TEST: PROC OPTIONS (MAIN) ; 

DCL (MTHlDEXP) 

ENTRY (FLOAT(53)) RETURNS (FL0AT(53)); 

DCL OPERAND FLOAT(53); 

DCL RESULT FLOAT(53); 

/*** Begin test ***/ 

OPERAND = 3.456; 

RESULT = MTH$DEXP(OPERAND); 

PUT EDIT ( 1 MTH$DEXP of \ OPERAND. ' is RESULT)(A(12),F(5,3).A(4),F(20,15)); 

END TEST; 


* 

* 

* 


Output: 

MTHIDEXP of 3.456 is 31.689962805379165 


B A 

* * 

* This program tests a MTH$H entry point. * 

* Note that in the PL/I statement below, the /G.float switch * 

* is needed to compile both G and H_floating point MTH$ routines. */ 


TEST: PROC OPTIONS (MAIN) ; 

DCL (MTH$HEXP) 

ENTRY (FLOAT (113), FLOAT (113)) ; 

DCL OPERAND FLOAT (113); 

DCL RESULT FLOAT (113); 

/*** Begin test ***/ 

OPERAND * 1.234578901234567891234567892; 

CALL MTH$HEXP(RESULT,OPERAND); 

PUT EDIT ('MTHSHEXP of OPERAND, ' is ', RESULT) (A(12),F(29,27),A(4),F(29,27)); 
end test; 


$ PLI/G.FLOAT EXAMPLE 
$ LINK EXAMPLE 
$ RUN EXAMPLE 

output: 

MTH$HEXP of 1.234578901234567891234567892 is 
3.436930928565989790506225633 
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5 String Procedures 


This section discusses how the Run-Time Library procedures handle strings. 
It also introduces the Run-Time Library procedures that perform string 
manipulation. 

The following topics are discussed: 

• Types of strings recognized by Run-Time Library procedures 

• Relationship of descriptor classes to string semantics 

• Differences in string handling among the LIB$, OTS$, and STR$ facilities 
of the Run-Time Library 

• Conventions for reading and writing string arguments in the Run-Time 
Library string procedures 

• Selection of the proper string manipulation procedures 

• Allocation and deallocation of dynamic string resources 


5.1 String Semantics in the Run-Time Library 

The semantics of a string refers to the conventions that determine how a 
string is stored, written, and read. The VAX architecture supports three string 
semantics: fixed-length, varying-length, and dynamic length. 


5.1.1 Fixed-Length Strings 

Fixed-length strings have two attributes: 

• An address 

• A length 

The length of a fixed-length string is constant. It is usually initialized when 
the program is compiled or linked. After initialization, this length is read 
but never written. When a Run-Time Library procedure copies a source 
string into a longer fixed-length destination string, the procedure pads the 
destination string with trailing blanks. 

When you pass a string to a Run-Time Library procedure, you pass the string 
by descriptor. For a fixed-length string, the descriptor must contain this 
information: 

• The descriptor class 

• The data type of the string 

• The length of the string 

• The address of the beginning of the string 
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In most cases, you will not have to construct an actual descriptor. By default, 
most VAX languages pass strings by descriptor. For information about how 
the language you are using handles strings, see your language reference 
manual. For more information about descriptors used for fixed-length strings, 
see Section 2.9.2 in the Introduction to VAX/VMS System Routines. 

Note: In contrast to Run-Time Library procedures, system services do not 
pad output strings. For this reason, when a program calls a system 
service that returns a fixed-length string, the program should supply an 
additional argument which indicates how many bytes the system service 
actually deposited in the fixed-length buffer of the calling program. Some 
system service routines have corresponding Run-Time Library procedures 
that provide the proper semantics for fixed-length, varying-length, and 
dynamic output strings. 


5.1.2 Varying-Length Strings 

Varying-length strings have the following three attributes: 

• A current length 

• An address 

• A maximum length 

The current length of a varying-length string is stored in a 2-byte field, called 
CURLEN, preceding the text of the string. The address of the string points to 
the beginning of this CURLEN field, not to the beginning of the string's text. 

The maximum string length is a field in the string's descriptor. The maximum 
string length field specifies how much space is allocated to the string in a 
program. The maximum string length is fixed and does not change. 

The value in the CURLEN field specifies how many bytes beyond the 
CURLEN field are occupied by the string's text. The character positions 
beyond this range are reserved for the growth of the string. Their contents 
are undefined. 

For example, assume a varying string whose CURLEN is 3 and whose 
maximum length is 6. If a string 'ABCD' is copied into this string, the result 
is 'ABCD' and the CURLEN is changed to 4. If a string 'XYZ'is now copied 
into the same varying string, the resulting string is 'XYZ' with a CURLEN of 
3. The maximum length is still 6. The bytes beyond the range designated by 
CURLEN are undefined. 


5.1.3 Dynamic-Length Strings 

Dynamic-length strings have two attributes: 

• A current length 

• An address pointing to the beginning of the text 

Theoretically, dynamic strings have unbounded length. The length field is an 
unsigned value occupying two bytes, however, so that its maximum value is 
65,535. Thus the length of a dynamic string is limited to 65,535 characters. 

In most cases, a program allocates only the descriptor for this kind of string. 
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The actual space for a dynamic-length string is allocated from heap storage 
by the Run-Time Library. When a Run-Time Library procedure copies a 
character string into a dynamic string, and the currently allocated heap 
storage is not large enough to contain the string, the currently allocated 
storage returns to a pool of heap storage maintained by the string procedures. 
Then the string routines obtain a new area of the correct size. As a result of 
this process of deallocation and reallocation, both the current-length field and 
the address portion of the string's descriptor may change. Often, dynamic 
strings are the most convenient type to write. 

The Run-Time Library string manipulation procedures are the only 
procedures that you should use to alter the length or address of dynamic 
strings. Do not use LIB$GET_VM for this purpose. For information on 
allocating dynamic strings, see Section 5.4. 


5.1.4 Examples 

The following examples illustrate what happens when the string 'ABCDEF' 
(of length 6) is copied into various destination strings. 

• Fixed-length string 

If 'ABCDEF' is copied into a fixed-length string, three results are possible: 

1 If the length of the output string is greater than the length of the 
source string, the string is padded with trailing spaces. 

Length of output string 10 

Result 'ABCDEF 

2 If the length of the output string is the same as that of the input string, 
the string is simply copied with no modification. 

Length of output string 6 

Result 'ABCDEF' 

3 If the length of the output string is less than the length of the source 
string, truncation on the right occurs. 

Length of output string 3 

Result 'ABC' 

• Varying-length string 

If the same string ('ABCDEF' ) is copied into a varying-length string, two 
results are possible: 

1 If the MAXSTRLEN field of the destination is greater than or equal 
to the length of the source, the input string is written into the output 
string without modification, and the CURLEN (current length) field of 
the output string becomes 6. 

2 If the MAXSTRLEN field of the destination is less than the length 
of the source string, the source string is truncated on the right and 
the CURLEN field is rewritten to its current length. For example, if 
MAXSTRLEN = 4, the resulting string contains 'ABCD' and 
CURLEN = 4. 
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• Dynamic length string 

If a Run-Time Library procedure copies the string 'ABCDEF' into a 

dynamic destination string, three results are possible: 

1 If the length of the destination string is greater than the length of the 
source string (6), the result is a dynamic string of length 6 containing 
'ABCDEF'. No padding takes place. The Run-Time Library may 
deallocate the string and reallocate a new string closer in length to the 
length of the source string. 

2 If the length of the destination string is less than the length of the 
source string, the result is also 'ABCDEF', with a length of 6. The 
Run-Time Library deallocates the destination string and allocates a 
new string large enough to hold the 6 characters. 

3 If the destination string and source string are of equal length, a simple 
copy is done. No allocation, deallocation, or padding takes place, and 
the destination descriptor is not modified. 


5.2 Descriptor Classes and String Semantics 

A calling program passes strings to a Run-Time Library string procedure by 
descriptor. That is, the argument list entry for an input or output string is 
actually the address of a string descriptor. The calling program allocates a 
descriptor for the input string that indicates the string's address and length, 
so that the called procedure can find the string's text and operate on it. The 
calling program also allocates a descriptor for the output string. In addition to 
length and address fields, each descriptor contains a field (DSC$B_CLASS) 
indicating the descriptor's class. The Run-Time Library procedure reads the 
class field to determine whether to write the output string as a fixed-length, 
varying-length, or dynamic-length string. 

To determine the address and length of the data in the input string, Run-Time 
Library procedures call LIB$ANALYZE_SDESC or STR$ANALYZE_SDESC. 
LIB$ procedures call LIB$ANALYZE_SDESC; STR$ procedures call 
STR$ANALYZE_SDESC, so that they can signal errors instead of returning a 
status. 

These procedures provide a centralized facility for analyzing string 
descriptors, so that string-handling procedures can function independently 
of the class of the input string. This means that if the Run-Time Library 
recognizes new string types, only the analysis procedure needs to be changed, 
not the string procedures themselves. If you are writing a procedure that 
recognizes all the string types recognized by the Run-Time Library, your 
procedure should first call LIB$ANALYZE_SDESC or STR$ANALYZE_ 
SDESC to obtain the address and length of the input string. 

You can also use the string descriptor analysis procedures to find the length 
of a returned string. Assume that your called procedure calls one of the 
Run-Time Library string-copying procedures to create a new string. You 
now want the called procedure to return the actual length of the new string 
to the calling program. The called procedure calls LIB$ANALYZE_SDESC 
to compute this length. This sequence of calls allows you to create the new 
string without knowing its ultimate length at the time it is created. 
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The Run-Time Library procedures recognize the following classes of string 
descriptors: 

• Z—unspecified 

• S—scalar, fixed-length string 

• SD—decimal scalar 

• VS—varying-length string 

• D—dynamic string 

• A—array 

• NCA—noncontiguous array 

For a detailed description of these descriptor classes and their fields, see the 
VAX Procedure Calling and Condition Handling Standard in Introduction to 
VAX/VMS System Routines. 

Table 5-1 indicates how the Run-Time Library procedures access the fields of 
the descriptor for input and output string arguments. Given the class of the 
string and the field of the descriptor, the table shows whether the procedure 
reads, writes, or modifies the field. 


Table 5-1 String Passing Techniques Used by the Run-Time 
Library 


String Type 

String Descriptor Fields 
Class Length 

Pointer 

Input Argument to Procedures 

Input string Passed by descriptor 

Read 

Read 

Read 

Output Argument from Procedures 

Called Procedure Assumes the Descriptor 
Class 




Output string passed by 
descriptor,fixed-length 

Ignored 

Read 

Read 

Output string passed by 
descriptor,dynamic 

Ignored 

Read,may 
be 

modified 

Read, 
may be 
modified 

Output Argument from Procedures, Calling 
Program 

Specifies the Descriptor Class in the 
Descriptor 




Output string, fixed-length— 

DSC$K_CLASS = S, Z, A, NCA, 

SD 

Read 

Read 

Read 

Output string, dynamic— 

DSC$K_CLASS_D 

Read 

Read, may 
be 

modified 

Read, 
may be 
modified 

Output string, varying-length— 
DSC$K_CLASS_VS 

Read 

MAXSTRLEN 

is 

read; 

CURLEN is 
modified 

Read 
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5.2.1 Conventions for Reading Input String Arguments 

When a calling program passes an input string as an argument to a Run-Time 
Library procedure, the argument list entry is the address of a descriptor. The 
called procedure examines the class code field of the descriptor to determine 
where the procedure will look to find the length of the string and the first 
byte of the string's text. For each descriptor class. Table 5-2 indicates which 
field of the descriptor the procedure uses to locate the text and length of the 
string. For diagrams of the descriptors, see the VAX Procedure Calling and 
Condition Handling Standard in Introduction to VAX/VMS System Routines. 


Table 5-2 How Run-Time Library Procedures Read Strings 


Class 

Length 

Address of first byte of data 

Z 

DSC$W_LENGTH 

DSC$A_POINTER 

s 

DSC$W_LENGTH 

DSC$A_POINTER 

D 

DSC$W_LENGTH 

DSC$A_POINTER 

A 

DSC$I_ARSIZE 

DSC$A_POINTER 

SD 

DSC$W_LENGTH 

DSC$A_POINTER 

NCA 

DSC$I_ARSIZE 

DSC$A_POINTER 

VS 

Word at DSC$A_POINTER 
(CURLEN field) 

Value of DSC$A_POINTER + 2 (Byte 
after CURLEN field) 


Notes 

1 If the descriptor class is NCA, it is assumed that the string is actually 
contiguous. 

2 If the descriptor class is A or NCA, the element size is assumed to be one 
byte. 

3 If the descriptor class is A or NCA, and the array being passed is 
multidimensional, you should be aware of how your language stores 
arrays (by column or by row). 


5.2.2 Semantics for Writing Output String Arguments 

Normally, Run-Time Library procedures return the result of an operation in 

one of two ways: 

• The called procedure returns the result as a function value in R0/R1. If the 
result is too large to fit in R0/R1, it is returned as a function value in the 
first position in the argument list, and the other arguments are shifted one 
position to the right. 

• The called procedure returns the result as an output argument. The calling 
program passes to the called procedure an argument naming a variable in 
which the procedure will write the output string. In each RTL procedure, 
the access field of an output argument contains "write only". 
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The STR$ procedures that produce string results use the first method to 
pass the results back to the calling program. Because a return string, by 
definition, does not fit in R0/R1, the function value from an STR$ procedure 
is placed in the first position in the argument list. On the other hand, the 
string manipulation procedures in the LIB$ and OTS$ facilities use the second 
method. They return their results as output arguments. 

For example, there are three alternate entry points for the string-copying 
procedure, LIB$SCOPY_DXDX, OTS$SCOPY_DXDX, and STR$COPY_DX. 
These copy the source string (src-str) to the destination string (dst-str). Their 
formats are as follows: 

LIB$SCOPY_DXDX(src-str .dst-str) 

0TS$SC0PY_DXDX(src-str .dst-str) 

STR$COPY_DX(dst-str ,src-str) 

Because the STR$ entry point places the result string in the first position, you 
can call STR$COPY_DX using a function reference in languages that support 
string functions. In FORTRAN, for example, you can use a function reference 
to invoke STR$COPY_DX in the following two ways: 

CHARACTER * 80 STR$COPY_DX 
ISTAT = STR$COPY_DX(DST, SRC) 

DST = STR$COPY_DX(SRC) 

If you use the second form, you cannot access the return status, which is used 
to indicate truncation. 

If you use a function reference to invoke a string manipulation procedure in 
a language that does not support the concept of a string function (such as 
MACRO, BLISS, and PASCAL), you must place the destination string variable 
in the argument list. In PASCAL, for example, you can use a function 
reference to invoke STR$COPY_DX as follows: 

STATUS := STR$COPY_DX(DST. SRC); 

However, the following statement will result in an error: 

DST := STR$COPY_DX(SRC) 

In addition to allocating a variable for the output string, the calling program 
must allocate the space for and fill in the fields of the output string descriptor 
at compile, link, or run time. High-level languages do this automatically. 

When a Run-Time Library procedure returns an output string argument to the 
calling program, the argument list entry is the address of a descriptor. The 
procedure determines the semantics of the output string (fixed, varying, or 
dynamic) by examining the class of the descriptor for the destination string. 
Given the class of the output string's descriptor. Table 5-3 specifies the type 
of semantics used by Run-Time Library routines when writing the string. 


Semantics and Descriptor Classes 


Table 5-3 

Class Description 

Z Unspecified 

S Scalar, string 

D Dynamic string 


Restrictions 

Treated as class S 
None 

String length < 64K bytes 
(DSC$W_LENGTH < 64K) 


Semantics 

Fixed-length string 
Fixed-length string 
Dynamic string 
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Table 5-3 Semantics and Descriptor Classes (Cont.) 


Class 

Description 

Restrictions 

Semantics 

A 

Array 

Array is one-dimensional 

Fixed-length string 



String length < 64K bytes 

(DSC$I_ARSIZE < 64K) 

Length of array elements is one byte 
(DSC$W_LENGTH = 1) 


SD 

Scalar decimal 

DSC$B_DIGITS and DSC$B_SCALE 
are ignored 

Fixed-length string 

NCA 

Noncontiguous 

array 

Array is one-dimensional 
(DSC$B_DIMCT = 1) 

String length < 64K bytes 

(DSC$I_ARSIZE < 64K) 

Array is contiguous 

(DSC$I_SI = DSC$W_LENGTH) 

Length of array elements is one byte 
(DSC$W_LENGTH = 1) 

Fixed-length string 

VS 

Varying string 

Current length less than maximum 
length of string 
(CURLEN <= DSC$W_ 

MAXSTRLEN) 

Varying string 


When a called procedure returns a string whose length cannot be determined 
by the calling procedure, the calling procedure should also pass an optional 
argument to contain the output length. This argument should be an unsigned 
16-bit integer. If the output string is a fixed-length string, the length 
argument would reflect the number of characters written, not counting 
the fill characters. 

The output length argument is useful, for instance, when your program is 
reading variable-length records. The program can read the input strings 
into a buffer that is large enough to contain the largest. When you wish to 
perform the next operation on the contents of the buffer, the length argument 
indicates exactly how many characters have been read, so that the program 
does not need to manipulate the whole buffer. 

For example, LIB$GET_INPUT has the optional argument out-len. If 
LIB$GET_INPUT is called with a fixed-length, 5-character string as an 
argument, and the procedure reads a record containing 'ABC', then out- 
len will have a value of 3 and the output string will be 'ABC ' . But if the 
procedure reads a record containing the value 'ABCDEFG', out-len will have 
a value of 5, and the output string will be 'ABCDE'. In either case, the calling 
program will know exactly how many characters (not counting fillers) the 
procedure has read. 

A procedure such as STR$COPY_DX does not need the length argument, 
because the calling program can determine the length of the output string. If 
the output string is dynamic, the length is the same as the input string length. 
If the output string is fixed length, the length is the shorter of the two input 
lengths. 
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5.3 Selecting String Manipulation Procedures 

To perform a given string manipulation operation, you can often choose 
one of several procedures from the Run-Time Library. The LIB$, OTS$, 
and STR$ facilities all contain string copying and dynamic string allocation 
procedures. Furthermore, a MACRO or BLISS program can call several of 
these procedures using either a JSB or CALL entry point. 

You should consider the factors discussed below when choosing the 
procedure to perform the desired operation. 


5.3.1 Efficiency 

One of the major considerations in choosing among several procedures is the 
efficiency of the various options. 

In general, LIB$ and STR$ procedures execute more efficiently than the 
corresponding OTS$ procedures. OTS$ routines usually invoke the LIB$ 
entry point to perform an operation. 

JSB entry points usually execute more efficiently than CALL entry points. 
However, a high-level language cannot explicitly access a JSB entry point. 
Further, a JSB entry point does not establish a stack frame and executes 
entirely in the environment of the calling program. This means, for instance, 
that the called procedure cannot establish its own condition handler, so it 
cannot regain control if an exception occurs during execution. Also, some 
of the efficiency gained by using the JSB may be lost because the calling 
procedure must explicitly save all of the registers that the called procedure 
will use. (See Section 2.3.2 for a complete discussion of JSB entry points.) 

Some procedures perform a specific operation that is a subset of a more 
general capability. These more specialized procedures are usually more 
efficient. For example, if you want to join two strings together, STR$APPEND 
and STR$PREFIX are more specific, and more efficient, than STR$CONCAT. 
Similarly, STR$LEFT and STR$RIGHT are subsets of the capabilities of 
STR$POS_EXTR. 


5.3.2 Argument Passing 

The mechanism by which a procedure passes or receives arguments may also 
help you to decide among several procedures which perform basically the 
same function. 

Procedures in the LIB$ and STR$ facilities pass scalar input arguments by 
reference to CALL entry points and by immediate value to JSB entry points. 
OTS$ procedures pass scalar input arguments by immediate value to all entry 
points. For most high-level languages, the default passing mechanism is 
by reference. Thus if you call a LIB$ or STR$ procedure from one of these 
languages, it will not be necessary to specify the passing mechanism for input 
scalar arguments. 

Some procedures require you to set up and pass more arguments than others. 
For example, some use a single string descriptor, while others require separate 
arguments for the length and the address of the string. Which procedure you 
choose will then depend on the form of the information already available in 
your program. 
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5.3.3 Error Handling 

Procedures from the LIB$, OTS$, and STR$ facilities handle errors in string 
copying differently: 

• LIB$ 

The LIB$ string-copying procedures return a completion status. When 
an output string must be truncated and its length depends on input 
arguments, LIB$ procedures consider this to be a partial success; they 
therefore return LIB$_STRTRU instead of a severe error. This process 
corresponds to the convention of many higher-level languages, which do 
not consider truncation to be an error. 

• STR$ 

The STR$ string-copying procedures generally signal errors instead of 
returning a completion status. In the case of truncation errors, STR$ 
procedures return an error status with a severity of WARNING (STR$_ 
TRU). STR$ procedures consider range errors to be qualified success. 
Range errors are defined in the introduction to this section. 

• OTS$ 

The OTS$ string-copying procedures also signal errors that are considered 
fatal (such as invalid descriptor class). However, they are designed to 
leave the registers as they would be after a MOVC5 Instruction. Thus, 
the call entry point, like MOVC5, returns in RO the number of bytes in 
the source string that were not moved to the destination string. The JSB 
entry points for OTS$ string-copying procedures also leave registers R1 
through R5 as they would be after a MOVC5 instruction. See the VAX-11 
Architecture Reference Manual for a complete description of the MOVEC5 
instruction. 

The following list indicates the errors that each facility considers severe, and 
the corresponding message: 


Error 

LIB$_ 

OTS$_ 

STR$ 

Fatal internal error 

FATERRLIB 

FATINTERR 

FATINTERR 

Illegal string class 

INVSTRDES 

INVSTRDES 

ILLSTRCLA 

Insufficient virtual memory 

INSVIRMEM 

INSVIRMEM 

INSVIRMEM 


Some Run-Time Library procedures require you to specify the length of a 
string or the position of a character within a string. The maximum length 
for a string in VAX/VMS is 65,535 characters. When you refer to character 
positions in a string, the first position is 1. Given a string with length L, 
containing a substring specified by character positions M to N, the following 
evaluation rules apply: 

• If M is less than 1, M is considered to equal 1. 

• If M is greater than L, the substring specified is the null string. 

• If N is greater than L, N is considered to equal the length of the source 
string. 

• If M is greater than N, the substring specified is the null string. 
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When specifying a substring by length L, the following applies: 

• If L is less than 0, the substring specified is the null string. (A null string 
is a descriptor with zero length. A descriptor with a nonzero length and a 
zero pointer generates an error and yields unspecified results.) 

If any of these evaluation rules apply, the range error status (qualified success) 
is returned. STR$POSITION represents the exception to this convention. This 
procedure returns a function value giving the character position of a substring 
within a string. If the function value is zero, the substring was not found. 


5.4 Allocating Resources for Dynamic Strings 

This section tells how to use the Run-Time Library string resource allocation 
procedures. These procedures allocate virtual memory for a dynamic string 
and place the address of the allocated memory in a descriptor. 

Dynamic strings may be the most convenient type to write, since you need 
not specify constant length, maximum length, or position for them. However, 
there are some restrictions on dynamic strings. 

• They may cause program execution to be slower at run time. 

• They require larger address space. 

• They are not supported by all VAX languages. 

In most cases, when you call a Run-Time Library procedure to manipulate 
dynamic strings, the Run-Time Library procedure itself allocates the required 
memory for the string. Your program needs to allocate the descriptors. 

For example, if you are copying a source string into a dynamic destination 
string, simply use one of the library's string-copying procedures. Copy the 
input string into a dynamic-string whose length and address have been 
initialized to zero. The string copying procedure itself will then allocate the 
space that the calling program needs. 

However, if your program must explicitly construct or modify a dynamic 
string descriptor, it must use the Run-Time Library allocation and deallocation 
procedures. This technique may be necessary, for instance, if you are 
constructing a string out of components that are not themselves in string 
form. Further, you can use one of the deallocation procedures to free the 
dynamic string after the string resources are no longer needed, in order to 
optimize the program's use of resources. 

The Run-Time Library provides eight entry points for string resource 
allocation and deallocation, all with slightly different input arguments, calling 
techniques, or methods of indicating errors. The following lists summarize 
these procedures and their functions. 

The following procedures allocate a specified number of bytes of dynamic 
virtual memory to a specified string descriptor. 

LIB$SGET1_DD 

LIB$SGET1_DD_R6 

OTS$SGETl_DD 

OTS$SGETl_DD_R6 

STR$GET1_DX 

STR$GET1_DX_R4 
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Returns one dynamic string area to free storage. Sets DSC$A_POINTER and 
DSC$W_LENGTH to zero. 

LIB$SFREE1_DD 
LIB$ SFREE1 _DD 6 
OTS$SFREEl_DD 
OTS$SFREE 1_DD6 
STR$FREE1_DX 
STR$FREE1_DX_R4 

Returns one or more dynamic string areas to free storage. Sets DSC$A_ 
POINTER and DSC$W_LENGTH to zero. 

LIB$SFREEN_DD 

LIB$SFREEN_DD6 

OTS$SFREEN_DD 

OTS$SFREEN_DD6 

If you find it necessary to call the dynamic string allocation procedures, there 
are several factors to consider. 

• When your program calls a string allocation procedure, it needs to allocate 
space only for the string descriptor before making the call. Your program 
does this using the statement of the particular language, either statically at 
compile time, or dynamically in local stack storage or heap storage. 

• If your procedure explicitly allocates dynamic string descriptors in stack 
storage, it must explicitly free the associated dynamic string areas by 
calling the LIB$SFREE1_DD, OTS$SFREEl_DD, or STR$FREE1_DX 
procedures. Then, your procedure must free the storage for the descriptor. 
After both areas have been freed, your procedure can return to the calling 
program. If the deallocation is not done, the dynamic string area becomes 
unavailable when the RET instruction removes the descriptors which point 
to the string area. 

• If a procedure has explicitly allocated dynamic string areas, and the 
procedure is then unwound by the condition handling facility, the 
allocated address space cannot be referenced again. For this reason, 
your program should establish a handler that will free the associated 
dynamic string areas when the SS$_UNWIND condition is signaled. The 
handler can free these areas by calling one of the deallocation procedures. 
This technique is especially important if a large amount of address space 
is involved, or if the procedure allocates space within a repeating loop. 

You can call the string resource allocation procedures only from user mode, 
at AST or non-AST level. However, be extremely careful if you manipulate 
dynamic strings at AST level. The string manipulation procedures in the 
Run-Time Library do not prevent the strings that they are manipulating at 
non-AST level from being modified at AST level. 

For example, consider the case in which a string manipulation procedure has 
calculated the lengths and addresses involved in a concatenation operation. 
This string manipulation procedure may be interrupted by an AST. The user, 
at AST level, may write to the same string, changing its length and address. 

It is then possible to resume execution of the procedure with addresses that 
are no longer allocated or string lengths that are no longer valid. For this 
reason, if you use dynamic strings at AST level, you should allocate, use, and 
deallocate them within the AST code. 
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The dynamic string manipulation procedures are intended for use at user 
mode only. If you need to manipulate dynamic strings at another access 
mode, you should allocate and deallocate storage for each string at that access 
mode to avoid side effects. Link each segment of your program that will run 
at a different access mode with the /NOSYSSHR qualifier. In this way, you 
will establish a separate copy of the string data base for each access mode. 


5-13 
















Cross-Reference Procedures 


The cross-reference procedures are contained in a separate, shareable image 
capable of creating a cross-reference analysis of symbols. They accept 
cross-reference data, summarize it, and format it for output. Two facilities 
that use the cross-reference procedures are the VAX/VMS Linker and the 
MACRO assembler. They are sufficiently general, however, to be used by 
any native-mode utility. 

Table 6-1 lists the entry points and functions of the cross-reference 
procedures. 

Table 6-1 Cross-Reference Procedures 


Entry Point 

Function 

LIB$CRF_INS_KEY 

Insert key information 

LIB$CRF_INS_REF 

Insert reference information 

LIB$CRF_OUTPUT 

Summarize and format cross-reference information 


ZK-4259-85 


The interface to the cross-reference procedures is by way of a set of control 
blocks, format definition tables, and a set of callable entry points. Macros are 
provided for assembly language and BLISS initialization of the control blocks 
and format definition tables. 


Using the Cross-Reference Procedures 

Using the cross-reference procedures involves the following steps: 

1 Defining a table of control information, using the $CRFCTLTABLE macro. 

2 Defining each field of the output line, using the $CRFFIELD macro. 

3 Specifying the end of each set of macros that define a field in the output 
line, using the SCRFFIELDEND macro. 

4 Providing data by calling one of the two following cross-reference entry 
points: 

• LIB$CRF_INS_JKEY inserts an entry for the specified key in the 
specified symbol table. 

• LIB$CRF_INS_REF inserts a reference to a key in the specified symbol 
table. 
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5 Calling LIB$CRF_OUTPUT, the cross-reference output procedure, to 
summarize and format the data. 

6 Supplying a routine that the output procedure calls to print each line 
in the output file. Because you supply this routine, you can control the 
number of lines per page and the header lines. 

Figure 6-1 illustrates the steps required in using the cross-reference 

procedures. 

Figure 6-1 Using Cross-Reference Procedures 


Step 1: 


Step 2: 


Step 3: 



ZK-1 970-84 


The Run-Time Library provides three macros to initialize the data structures 
used by the cross-reference procedures: 

1 $CRFCTLTABLE defines a table of control information. 

2 $CRFFIELD defines each field of the output format definition table. 
Multiple $CRFFIELD macro instructions can be issued in defining one 
particular field. 

3 $CRFFIELDEND ends a set of $CRFFIELD macro instructions (a format 
table). 


6.2 $CRFCTLTABLE Macro 

$CRFCTLTABLE initializes a cross-reference control table. Your program 
must issue one $CRFCTLTABLE macro for each cross-reference table you 
build. You can accumulate information for more than one cross-reference 
table at a time. For this reason, you must define a table for each set of 
cross-references, and include the address of that table each time you call a 
cross-reference procedure to insert data. 
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The $CRFCTLTABLE macro instruction has the following format: 

label: $CRFCTLTABLE keytype, output, error, memexp, keyltable, 
key2table, valltable, val2table, 
rentable, ref2table 


label 

Address of the control table. You must specify a control table address in all 
calls to the cross-reference procedures. 

keytype 

Type of key to be entered in the table. The following key types are defined: 

ASCIC Keys are counted ASCII strings, with a maximum of 31 characters 

(symbol name). 

BIN_U32 Keys are 32-bit unsigned binary values. The binary-to-ASCII 

conversion is done by $FAO using the format string for the KEY1 
field. 

output 

Address of routine that you supply to print a formatted output line. 

error 

Address of an error routine to execute if the called cross-reference procedure 
encounters an error. A value of zero indicates that no error routine is 
supplied. 

memexp 

Number of pages by which to expand region when needed. The default is 50. 

keyltable 

Address of the field descriptor table for the KEY1 field. A value of zero 
indicates that the field is not to be included in the output line. 

The remaining arguments provide the address of the field descriptor tables 
for the KEY2, VAL1, VAL2, REF1, and REF2 fields, respectively, of the output 
line. 

You can use these argument names as keywords in the macros. For example, 
you can use KEYTYPE as a keyword when issuing the $CRFCTLTABLE 
macro. 


6.3 $CRFFIELD Macro 

For each field in the output line, you must issue a $CRFFIELD instruction, in 
order to identify the field, supply an $FAO command string to control the 
printing of the field, and provide flag information. See the program example 
and the description of $FAO (formatted ASCII output) in the VAX/VMS 
System Services Reference Manual. The $CRFFIELD macro has the following 
format: 

label: $CRFFIELD bit_mask, lao_string, field.width, 
set_clear 
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label 

Address of the field descriptor table being generated as a result of this set of 
$CRFFIELD macro instructions. The label field can be omitted after the first 
macro of the set. These addresses correspond to the field descriptor table 
addresses in the $CRFCTLTABLE macro. 

bit—mask 

A 16-bit mask. When the user enters a key or reference, the cross-reference 
procedure stores flag information with the entry. When preparing the output 
line, LIB$CRF—OUTPUT ANDs the 16-bit mask in the field descriptor table 
with the flag stored with the entry. Any number of bit masks can be defined 
for a field. $CRFFIELD macro instructions are used to define multiple bit 
patterns for a flag field. The high-order bit is reserved to the cross-reference 
procedures. 

fao_string 

$FAO command string. LIB$CRF_OUTPUT uses this string to determine the 
$FAO format when formatting this field for output. 

field-width 

Maximum width of the output field. 

set_clear 

Indicator used to determine whether the bit mask is to be tested as set or 
clear when determining which flag to use. SET indicates test for set; CLEAR 
indicates test for clear. 

You can use the argument names shown here as keywords in your program. 

In the following example, one bit pattern is defined twice; once indicating a 
string that is to be printed if the pattern is set, and once indicating that spaces 
are to appear if the pattern is clear. 

$CRFFIELD BIT_MASK=SYM$M_REL, FA0_STRING=3_\##_\,- 

SET_CLEAR=CLEAR, FIELD_WIDTH=2 
$CRFFIELD BIT_MASK=SYM$M_REL, FAO_STRING=_\-R_\,- 

SET_CLEAR=SET, FIELD_WIDTH=2 

If more than one set of flags is defined for a field, each FAO string must 
print the same number of characters; otherwise, the output is not aligned in 
columns. 

The fields for the symbol name, symbol value, and references are always 
formatted using the first descriptor in the corresponding table. 


6.4 CRFFIELDEND Macro 

The $CRFFIELDEND macro instruction marks the end of a set of macros that 
describe one field of the output line. It is used once to end each set of field 
descriptors. It has the following format: 

$CRFFIELDEND 


6-4 







Cross-Reference Procedures 

Cross-Reference Output 




Cross-Reference Output 

LIB$CRF_OUTPUT can format output lines for three types of cross-reference 

listings: 

1 A summary of symbol names and their values, as illustrated in Figure 6-2. 

2 A summary of symbol names, their values, and the names of modules that 
refer to the symbol, as illustrated in Figure 6-3. 

3 A summary of symbol names, their values, the name of the defining 
module, and the names of those modules that refer to the symbol, as 
illustrated in Figure 6-4. 

Figure 6-2 Summary of Symbol Names and Values 



+ 

- + 
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BAS$STATUS 
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BAS$IN_F_R 
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BAS$STR_D 
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BAS$STR_F 
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BAS$IN_T_D)< 
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BAS$STR_L 
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BAS$IN_M_R 

0 0 0 0 2 1 D 8 - R U 

BAS$UNL0CK 
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BAS$LINKAGE 
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00002288-RU 
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Figure 6-3 

Summary of Symbol Names, 
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Figure 6-4 Summary Indicating Defining Module 


S y m b o 1 

0 a 1 u e 

Defined B y 

Referenced By 

LIB$FREE_OM 

000 IE 185-R 

L I B $ 0 M 

ALLGBL 

BAS$MARGIN 
BAS6XLATE 

F 0 R $ 0 M 
STR$APPEND 
STR$DUPL_CHAR 
STR$REPLACE 

LIB$GET_COMMAND 

0001E2B0-R 

L I B$GET_IN PUT 

ALLGBL 

LIB$GET_COMMON 

0001E4D6-R 

LIB$C0MM0N 

ALLGBL 
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Regardless of the format of the output, LIB$CRF_OUTPUT considers the 

output line as consisting of the following six different field types: 

1 KEY1 is the first field in the line. It contains a symbol name. 

2 KEY2 is the second field in the line. It contains a set of flags (for 
example,-R) providing information about the symbol. 

3 VAL1 is the third field in the line. It contains the value of the symbol. 

4 VAL2 is the fourth field in the line. It contains a set of flags describing 
VAL1. 

5 REF1 and REF2 fields. Within each REF1 and REF2 pair, REF1 provides a 
set of flags and REF2 provides the name of a module that references the 
symbol. 

Any of these fields can be omitted from the output as shown in the following 

figure. 


S y m b o 1 

0 a 1 u e 

BAS$INSTR 

f 

0 0 0 0 2 0 B 0 - R U 

t t 

1 

KEY1 

1 1 

VAL1 VAL2 

S y m b o 1 

0 a 1 Li e 

LIB$FREE_UM 

4 

0001E1B5-R 

4 4 

I 

KEY1 

T 1 

VAL1 VAL2 


S y m b o 1 

V a 1 u e 

BAS$SCRATCH 

4 

0 0 0 0 2 3 0 8 - R U 

4 4 

1 

KEY1 

1 1 

VAL1 VAL2 

Defined B y 

Referenced By 

L I B $ 0 M 

f 

ALLGBL 

4 

T 

REF2 

(CRF$K_DEF) 

T 

REF2 

(CRF$K_REF) 


ZK-1972-84 


Example 

The VAX Linker uses the cross-reference procedures to generate cross- 
reference listings. This section uses the linker's code as an example of using 
the cross-reference procedures in a MACRO program. 
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6.6.1 Defining Control Tables 

Cross-reference procedures use two control tables. 

• The symbol-by-name table 

• The symbol-by-value table 


First, the linker uses the $CRFCTLTABLE macro to set up the characteristics 
and fields of the symbol-by-name table. This table will list symbols by name 
and provide a cross-reference synopsis. The table is set up as follows: 

LNK$NAMTAB: 

$CRFCTLTABLE KEYTYPE=ASCIC.ERROR=LNK$ERR_RTN._ 

OUTPUT=LNK$MAPOUT,KEY1TABLE=LNK$KEY1._ 

KEY2TABLE=LNK$KEY2.VAL1TABLE=LNK$VAL1,_ 
VAL2TABLE=LNK$VAL2,REF1TABLE=LNK$REF1._ 
REF2TABLE=LNK$REF2 


LNK$NAMTAB 

KEYTYPE=ASCIC 

ERROR=LNK$ERR_RTN 

OUTPUT=LNK$MAPOUT 


Names the address of the control table 

Specifies that the keys are counted ASCII strings (that 
is, symbol names) 

Indicates that LNK$ERR_RTN is the address of the 
procedure to be executed in case of error 

Names LNKSMAPOUT as the address of the user- 
supplied routine that prints the formatted table 


The rest of the arguments provide the addresses of the field descriptor tables. 

After setting up the control tables, the linker defines each field of the 
cross-reference output line, using the $CRFFIELD macro. After each set of 
definitions for a field, it calls $CRFFIELDEND to mark the end of the field. 

Note particularly the following two features of this set of definitions. 

• The definition of LNK$VAL2 describes a flag to be associated with 
VAL1. The definition contains alternative bit patterns, depending on the 
bit mask. When an entry is made to the table, the entry contains flag 
information. Then, when LIB$CRF_OUTPUT is called to format the data, 
the procedure checks each entry, matching the flags argument against the 
bit masks specified in the control table. When LIB$CRF__OUTPUT finds a 
match, it uses that definition to determine the format of the entry in the 
output table. For example, BIT_MASK=SYM$M_DEF marks an entry as 
the defining reference. The corresponding VAL1 entry will be placed in 
the output table with an asterisk in its flags field. 

• The FAO control strings are defined to produce an output of the maximum 
character size for each field. This ensures that the columns will line up 
correctly in the output. For example, 115AC produces the variable symbol 
name left-aligned and right-filled with spaces. Another example is the 
three sets of characters to be printed for field VAL2. Each FAO control 
string produces two characters, which is the maximum size of the field. 


LNK$KEY1: 

$CRFFIELD BIT_MASK=0, FAO_STRING=\!15AC\,- 

SET_CLEAR=SET.FIELD_WIDTH=15 

$CRFFIELDEND 
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LNK$KEY2: 


LNKIVAL1: 


LNKIVAL2: 


LNK$REF1: 


LNK$REF2: 


$CRFFIELD 

BIT_MASK=0,FAO_STRING=\ \,- 
SET_CLEAR=SET, FIELD_WIDTH=1 

ICRFFIELDEND 


ICRFFIELD 

BIT_MASK=0,FAO_STRING=\!XL\,- 
SET_CLEAR=SET.FIELD_WIDTH=8 

$CRFFIELDEND 


ICRFFIELD 

BIT_MASK=0, FAO_STRING=\!2* \,- 

SET_CLEAR=SET,FIELD_WIDTH=2 

$CRFFIELD 

BIT_MASK=SYM$M_REL,FAO_STRING=\-R\.- 
SET_CLEAR=SET,FIELD_WIDTH=2 

$CRFFIELD 

BIT_MASK=SYM$M_DEF, FAO_STRING=\-*\,- 
SET_CLEAR=CLEAR,FIELD_WIDTH=2 

$CRFFIELDEND 


$CRFFIELD 

BIT_MASK=0,FAO_STRING=\!6* \.- 
SET_CLEAR=SET,FIELD_WIDTH=6 

ICRFFIELD 

BIT_MASK=SYM$M_WEAK,FAO_STRING=\!3* WK-\,- 
SET_CLEAR=SET.FIELD_WIDTH=6 

$CRFFIELDEND 


ICRFFIELD 

BIT_MASK=0,FAO_STRING=\!16AC\,- 
SET_CLEAR=SET,FIELD_WIDTH=16 

$CRFFIELDEND 



After initializing the symbol-by-name table, the linker sets up a second 
control table. This table defines the output for a symbol-by-value synopsis. 
For this output, the value fields are eliminated. The symbols having this 
value are entered as reference indicators. None is specified as the defining 
reference. The control table uses the field descriptors set up previously. The 
following macro instructions are used: 

LNK$VALTAB: 

$CRFCTLTABLE KEYTYPE=BIN_U32, ERROR=LNK$ERR_RTN,- 

OUTPUT=LNK$MAPOUT,KEY1TABLE=LNK$VAL1,- 
KEY2TABLE=LNK$VAL2,VAL1TABLE=0,- 
VAL2TABLE=0,REF1TABLE=LNK$REF1,- 
REF2TABLE=LNK$REF2 


6.6.2 Inserting Table Information 

After initializing the format data for the symbol tables, the linker enters data 
into the cross-reference tables by calling LIB$CRF_INS_KEY. 

As the linker processes the first object module, MAPINITIAL, it encounters 
a symbol definition for $MAPFLG. The following is an example of a call to 
enter the symbol MAPINITIAL as a key in the cross-reference symbol table: 

PUSHAB VALUE.FLAGS 

PUSHAB VALUE.ADDR 

PUSHAB SYMBOL_ADDR 

PUSHAB LNKINAMTAB 

CALLS #4,G~LIB$CRF_INS_KEY 


LNKSNAMTAB 

SYMBOI_ADDR 

VALUE_ADDR 

VALUE_FLAGS 


Is the address of the control table 

Is the address of the counted ASCII string $MAPFLG 

Is the address of the symbol value 

Is the address of a word whose bits are used to select special 
characters to print beside the value 
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The linker then calls LIB$CRF_INS_REF to process the defining reference 
indicator: 


DEF: .LONG 

PUSHAB 
PUSHAB 
PUSHAB 
PUSHAB 
PUSHAB 
CALLS 


CRF$K_DEF 

DEF 

REF.FLAGS 

REF.ADDR 

SYMBOL.ADDR 

LNK$NAMTAB 

#5.G~LIB$CRF_INS_REF 


LNKSNAMTAB 

SYMBOI_ADDR 

REF_ADDR 

REF_FLAGS 


Is the address of the control table 

Is the address of the counted string $MAPFLG 

Is the address of the referrer's counted ASCII string 

Is the address of a word whose bits are used to select special 
characters to print beside the reference 


Further on in the input module, the linker encounters a global symbol 
reference to CS$GBL. The call to store data for this reference is as follows: 


.LONG 

CRF$K_REF 

PUSHAB 

REF 

PUSHAB 

REF.FLAGS 

PUSHAB 

REF.ADDR 

PUSHAB 

SYMBOL.ADDR 

PUSHAB 

LNK$NAMTAB 

CALLS 

#5,G~LIB$CRF_INS_REF 


The arguments are similar to the previous example, except for CRF$K_REF, 
which indicates that this is not the defining reference. 

After it has performed symbol relocation for the module being linked, the 
linker calls LIB$CRF_INS_REF to build a table ordered by value. 


PUSHAB REF 

PUSHAB REF.FLAGS 

PUSHAB REF.ADDR 

PUSHAB VAL.ADDR 

PUSHAB LNK$VALTAB 

CALLS #5,G~LIB$CRF_INS_REF 


LNK$VALTAB 

VAI_ADDR 

REF_ADDR 

REF—FLAGS 

CRF$K_REF 


Is the address of the control table for the symbol synopsis by 
value 

Is the address of the value (binary longword key) 

Is the address of the symbol name having the value contained in 
VAI_ADDR 

Is the address of a word whose bits are used to select special 
characters to print beside the value 

Is the indicator that this is not a defining reference 


6.6.3 Formatting Information for Output 

After all the input modules are entirely processed, the linker requests the 
information for the map. It calls LIB$CRF_OUTPUT once for each type of 
output. Three calls are illustrated here. The following MACRO example 
illustrates a call to list the symbols and their values. 
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LNWID: 

.LONG 

132 

LNSP1: 

.LONG 

LINES.PAGEl 

LNSOP: 

.LONG 

LINES.OTHR.PAGE 

SAVE: 

.LONG 

CRF$K_SAVE 

VAL: 

.LONG 

CRF$K_VALUES 


PUSHAB 

VAL 


PUSHAB 

SAVE 


PUSHAB 

LNSOP 


PUSHAB 

LNSP1 


PUSHAB 

LNWID 


PUSHAB 

LNK$NAMTAB 


CALLS 

#6.G~LIB$CRF_OUTPUT 


In this example, CRF$K__VALUES means that no reference indicators are to 
be printed, while CRF$K_SAVE means that the cross-reference table is to be 
saved. It is also possible to list all cross-reference data. The type of output 
produced by this call is shown in Section 6.5, Figure 6-2. 

The following call produces such a summary and releases the storage at the 
same time: 


LNWID: 

.LONG 

132 

LNSP1: 

.LONG 

LINES.PAGEl 

LNSOP: 

.LONG 

LINES.OTHR.PAGE 

DELETE: 

.LONG 

CRF$K_DELETE 

DEFREF: 

.LONG 

CRF$K_DEF_REF 


PUSHAB 

DELETE 


PUSHAB 

DEFREF 


PUSHAB 

LNSOP 


PUSHAB 

LNSP1 


PUSHAB 

LNWID 


PUSHAB 

LNKtNAMTAB 


CALLS 

#6,G~LIB$CRF_OUTPUT 


The type of output produced by this call is shown in Section 6.5, Figure 6-4. 

CRF$K_DEFS__REFS indicates that the first two reference fields are to be used 
for the defining references, and CRF$K_DELETE indicates that the table is to 
be deleted. 

Another call is made to list the symbol by value synopsis, as follows: 


LNWID: 

.LONG 

132 

LNSP1: 

.LONG 

LINES.PAGEl 

LNSOP: 

.LONG 

LINES.OTHR.PAGE 

VALREF: 

.LONG 

CRF$K_VALS_REF 

DELETE: 

.LONG 

CRFSK.DELETE 


PUSHAB 

DELETE 


PUSHAB 

VALREF 


PUSHAB 

LNSOP 


PUSHAB 

LNSP1 


PUSHAB 

LNWID 


PUSHAB 

LNKlVALTAB 


CALLS 

#6,G~LIB$CRF_OUTPUT 


This is similar to the previous call in that it produces a complete cross- 
reference output by value, but it does not have the defining reference fields. 
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6.7 How to Link to the Cross-Reference Shareable Image 

The cross-reference procedures are located in a shareable image CRFSHR.EXE. 
This shareable image is part of the default system shareable image library, 
SYS$LIBRARY:IMAGELIB.OLB. For this reason, the cross-reference 
procedures are automatically included in your image, unless you specify 
/NOSYSHR in the LINK command. If you have specified /NOSYSHR and 
you wish to include CRFSHR.EXE, your LINK command must include the 
following: 

SYS$LIBRARY:IMAGELIB/INCLUDE=CRFSHR 


6-11 





















7 


Condition Handling Procedures 


This section describes the VAX Condition Handling Facility. It is divided into 
four subsections: 

Section 7.1 gives background information on the VAX Condition Handling 
Facility. It discusses exception conditions, the condition value, and signaling. 

Section 7.2 shows you how to use the capabilities of the VAX Condition 
Handling Facility by writing and setting up your own condition handlers, 
initiating the signaling mechanism, and signaling application-specific 
messages. 

Section 7.3 shows how to use Run-Time Library condition handling 
procedures. It also shows how to use the Run-Time Library procedures that 
enable and disable the signaling of certain hardware exceptions. 

Section 7.4 explains how Run-Time Library procedures handle exceptions. 

Table 7-1 is a list of Run-Time Library Condition Handling and Signaling 
Procedures. 


Table 7-1 Condition Handling and Signaling Procedures 

Procedure Function 


Establish a condition handler 

LIBSESTABLISH Establishes a Condition Handler 

LIBSREVERT Deletes a condition handler 


Enable or Disable Signaling of Hardware Exceptions 

LIB$DEC_OVER Enables or disables signaling of decimal overflow 

LIB$FLT_UNDER Enables or disables signaling of floating-point 

underflow 

LIB$INT_OVER Enables or disables signaling of integer overflow 


Generate Signals 

LIBSSIGNAL Signals an exception condition 

LIB$STOP Stops execution by using signaling 


Condition Handling Procedures 

LIB$DECODE_FAULT Analyze the instruction context for fault 

LIB$FIXUP_FLT Changes floating-point reserved operand to a specified 

value 


LIB$MATCH_COND Matches condition value 

LIB$SIG_TO_STOP Converts a signaled condition to a condition that 

cannot be continued 


LIB$SIG_TO_RET Converts any signal to return status 

LIB$SIM_TRAP Simulates a floating-point trap 
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7.1 An Overview of the VAX Condition Handling Facility 

VAX/VMS provides a set of signaling and condition handling procedures 
and related system services to handle exception conditions. This set of 
services is referred to as the VAX Condition Handling Facility. The VAX 
Condition Handling Facility is a part of the common run-time environment 
of VAX/VMS which includes Run-Time Library procedures and other 
components of VMS. 

The VAX Condition Handling Facility provides a single, unified method of 
enabling condition handlers, signaling conditions, printing error messages, 
changing the error behavior from the system default, and enabling or 
disabling detection of certain hardware errors. The RTL and all layered 
products of VAX/VMS use the VAX Condition Handling Facility for condition 
handling. 

See the Introduction to VAX/VMS System Routines for the functional 
specification of the VAX Condition Handling Facility. 

The following terminology is important in the understanding of the VAX 
Condition Handling Facility. 

Condition Handling Terminology 
Exception 

An event detected by the hardware or software that changes the normal 
flow of instruction execution. An exception is a synchronous event caused 
by the execution of an instruction. When an exception occurs, the processor 
transfers control by forcing a change in the flow of control from that explicitly 
indicated in the currently executing process. 

Some exceptions are relevant primarily to the currently executing process and 
normally invoke software in the context of the current process. An integer 
overflow exception detected by the hardware is an example of an event that 
is reported to the process. Other exceptions, such as page faults, are handled 
automatically by the operating system and are transparent to the user. 

An exception may also be signaled by a procedure (software signaling) by 
calling the RTL procedures LIB$SIGNAL or LIB$STOP. 

Condition 

An informational error state which exists when an exception occurs. The term 
condition is preferred since the term exception implies an error. The term 
exception condition is used interchangeably with the term condition. 

Condition handling 

When a condition is detected during the execution of a procedure, a signal 
can be raised by the procedure. (See "Signal a condition" under the list 
of functions below.) The procedure is then permitted to respond to the 
condition. The procedure's response is called "handling the condition". 

The condition handlers are themselves procedures; they have their own call 
frame. Since they are procedures, condition handlers can have condition 
handlers of their own. This allows condition handlers to field exceptions that 
might occur in themselves in a modular fashion. A procedure may enable a 
condition handler by placing the address of the condition handler in the first 
longword of its stack frame. 
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Parallel mechanisms exist for uniform dispatching of hardware and software 
exception conditions. Exceptions which are detected and signaled by 
hardware transfer control to an exception service routine in the executive. 
Software detected exception conditions are generated by calling the Run-Time 
Library procedures LIB$SIGNAL or LIB$STOP. Hardware and software 
detected exceptions eventually execute the same exception dispatching code. 
Therefore, a condition handler may handle an exception condition generated 
by hardware or by software identically. 

The VAX Condition Handling Facility and the related Run-Time Library 
routines and System services perform the following functions: 

• Establish and call condition handler procedures. 

You can associate a condition handler for the currently executing 
procedure by specifying an address pointing to the handler, either in 
the procedure's stack frame or in one of the exception vectors. Then, 
when the procedure signals an exception, the VAX Condition Handling 
Facility calls the condition handler associated with the procedure. See 
Section 7.1.3 for more information about exception vectors. See the VAX- 
11 Architecture Reference Manual for a description of the stack frame and 
exception vectors. See Figure 7-2 for a sample stack scan for a condition 
handler. 

Most high-level languages provide condition handling statements. 

BASIC's ON ERROR GOTO and PL/I's ON statements may be used 
to define condition handlers. If the language does not provide its own 
condition handling, the RTL procedure LIB$ESTABLISH may be used to 
enable condition handling. 

• Remove an established condition handler procedure. 

Using LIB$REVERT, you can remove a condition handler from a 
procedure's stack frame by setting the frame's handler address to zero. 

If your high-level language provides condition handling statements, you 
should use them rather than LIB$REVERT. 

• Enable or disable the detection of arithmetic hardware exceptions. 

Using Run-Time Library procedures, you can enable or disable the 
signaling of floating-point underflow, integer overflow, and decimal 
overflow, which are detected by the VAX hardware. 

• Signal a condition. 

When the hardware detects an exception, such as an integer overflow, a 
signal is raised at that instruction. A procedure may also raise a signal by 
calling LIB$SIGNAL or LIB$STOP. Signals raised by LIB$SIGNAL allow 
the condition handler to either terminate or resume the normal flow of 
the procedure. Signals raised by LIB$STOP require termination of the 
operation raising the condition. The condition handler will not be allowed 
to continue from the point of call to LIB$STOP. 

• Display an informational message. 

The system establishes default condition handlers before it calls the 
main program. Because these handlers provide access to the system's 
standard error messages, the standard method for displaying a message 
is by signaling if the condition has a severity of informational, warning, 
or error. See Section 7.1.2 for the definition of the severity field of a 
condition vector. The system default condition handlers will resume 
execution of the instruction after displaying the messages associated with 
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the signal. If the condition value indicates a severe condition, then the 
image is exited after the display of the message. 

• Display a stack traceback on errors. 

The default operations of the LINK and RUN commands provide a 
system-supplied handler (the traceback handler) to print a symbolic 
stack traceback. The traceback shows the state of the procedure stack 
at the point where the condition occurred. The traceback information is 
displayed along with the messages associated with the condition signaled. 

• Compile customer-defined messages. 

The VAX/VMS Message Utility allows you to define your own exception 
conditions and the associated messages. Message source files contain the 
condition values and their associated messages. See Section 7.2.4 for a 
complete description of how to define your own messages. 

• Unwind the stack. 

A condition handler can cause a signal to be dismissed and the stack to 
be unwound to the establisher or caller of the establisher of the condition 
handler when it returns control to the VAX Condition Handling Facility. 
During the unwinding operation, the VAX Condition Handling Facility 
scans the stack. If a condition handler is associated with a frame, the 
system calls that handler before removing the frame. Calling the condition 
handlers during the unwind allows a procedure to perform cleanup 
operations specific to a particular application, such as recovering from 
noncontinuable errors or deallocating resources that were allocated by 
the procedure (such as virtual memory, event flags, and so forth). See 
Section 7.2.2.3 for a description of the $UNWIND system service. 

• Log error messages to a file. 

The Put Message system service ($PUTMSG) permits any user-written 
handler to include a message in a listing file. Such message logging can 
be separate from the default messages the user receives. See Section 7.1.5 
for a detailed description of the $PUTMSG system service. 


7.1.1 Exception Conditions 

An exception condition is an event, detected either by hardware or software, 
that changes the normal flow of instruction execution. Some examples of 
exception conditions are as follows: 

• Arithmetic exception condition in a user-written program detected and 
signaled by hardware (for example, floating-point overflow) 

• Error in a user argument to a Run-Time Library procedure detected by 
software and signaled by calling LIB$STOP (for example, a negative 
square root) 

• Error in Run-Time Library language-support procedure, such as an I/O 
error or an error in a data type conversion 
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• VAX RMS success condition. Record already locked 

• VAX RMS success condition. Created file superseded an existing version 

There are two standard methods for a DIGITAL- or user-written procedure to 
indicate that an exception condition has occurred: 

1 Return a condition value to the calling program using the function value 
mechanism 

Most general-purpose Run-Time Library procedures indicate exception 
conditions by returning a condition value in RO. The calling program 
then tests bit 0 of RO for success or failure. This method allows better 
programming structure, because the flow of control can be changed 
explicitly after the return from each call. 

2 Signal the exception condition 

A condition may be signaled by calling the RTL procedures LIB$SIGNAL 
or LIB$STOP. Any condition handlers that may have been enabled are 
then called by the VAX Condition Handling Facility. See Section 7.1.4.2 
for actions that a condition handler may take. See also Figure 7-2 for 
the order in which condition handlers are invoked by the VAX Condition 
Handling Facility. 

Exception conditions raised by hardware or software are signaled to the 
procedure identically. 

For more details, see Sections 7.1.3 and 7.2.3. 


7.1.2 The Condition Value 

Each exception condition has associated with it a unique 32-bit condition 
value that identifies the exception condition. Each condition value has a 
unique system-wide symbol and an associated message. The condition value 
is used in both methods of indicating exception conditions, returning a status 
and signaling. 

A condition value includes the following fields: 


Field 

Bits 

Meaning 

FAC—NO 

27 through 16 

Indicates the system facility in which the 
condition occurred. (See Table 2-1 for a list 
of library facilities and the numbers associated 
with them.) 

MSG—NO 

15 through 3 

Indicates the particular condition that occurred. 

SEVERITY 

2 through 0 

Indicates whether the condition is a success 
(bit 0 = 1) or a failure (bit 0 = 0) as well as the 
severity of the error. 
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Figure 7-1 shows the format of the condition value. 

Figure 7-1 Format of the Condition Value 


31 28 27 


3 2 0 



facility number 


message number 
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Condition Value Fields 
severity 

The severity code. Bit 0 is set for success (logical true) and clear for failure 
(logical false); bits 1 and 2 distinguish degrees of success or failure. Bits 0 
through 2 represent an unsigned integer, which is interpreted as follows: 


Name 

Code 

Meaning 

STS$K_ 

WARNING 

0 

Warning 

STS$K_SUCCESS 

1 

Success 

STS$K_ERROR 

2 

Error 

STS$K_INFO 

3 

Information 

STS$K_SEVERE 

4 

Severe error 


5,6,7 

Reserved to DIGITAL 


condition identification 

Identifies the condition uniquely on a system-wide basis. 

message number 

A status identification, that is, a description of the hardware exception 
condition that occurred or a software-defined value. Message numbers with 
bit 15 set are specific to a single facility. Message numbers with bit 15 clear 
are system-wide status codes. 

facility number 

Identifies the software component generating the condition value. Bit 27 is 
set for customer facilities and clear for DIGITAL facilities. 
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cntrl 

Four control bits. Bit 28 inhibits the message associated with the condition 
value from being printed by the $EXIT system service. After using the 
$PUTMSG system service to display an error message, the system default 
handler sets this bit. It is also set in the condition value returned by 
a procedure as a function value, if the procedure has also signaled the 
condition, so that the condition has been either printed or suppressed. Bits 29 
through 31 must be zero; they are reserved for future use by DIGITAL. 

When a software component completes execution, it returns a condition value 
in this format. When a severity code of WARNING, ERROR, or SEVERE has 
been generated, the status code returned describes the nature of the problem. 
Your program can test this value to change the flow of control or to generate 
a message. Your program can also generate condition values to be examined 
by other procedures and by the command language interpreter. Condition 
values defined by customers must set bits 27 and 15 so that these values will 
not conflict with values defined by DIGITAL. 


7.1.3 Signaling 

Signaling can be initiated when hardware or software detects an exception 
condition. In either case, the exception condition is said to be signaled by the 
procedure in which it occurred. If hardware detects the error, it passes control 
to a condition dispatcher. If software detects the error, it calls one of the 
Run-Time Library signal-generating procedures: LIB$SIGNAL or LIB$STOP. 
The RTL signal-generating procedures pass control to the same condition 
dispatcher. When LIB$STOP is called, the severity code is forced to SEVERE, 
and control cannot return to the procedure that signaled the condition. See 
Section 7.2.2.1 for a description of how a signal may be dismissed and normal 
execution from the point of the exception condition may be continued. 

When a procedure signals, it passes to the VAX Condition Handling Facility 
the condition value associated with the exception condition, as well as 
optional arguments that can be passed to a condition handler. The VAX 
Condition Handling Facility uses these arguments to build two data structures 
on the stack: the signal argument vector and the mechanism argument vector. 
These two vectors become the arguments that the VAX Condition Handling 
Facility passes to condition handlers. 

• The signal argument vector contains the information describing the nature 
of the exception condition. 

• The mechanism argument vector describes the state of the process at the 
time the exception condition occurred. 

These argument vectors are described in detail in Sections 7.1.3.1 and 7.1.3.2. 

After the signal and mechanism argument vectors have been set up, the 
VAX Condition Handling Facility searches for enabled condition handlers. 

A condition handler is a separate procedure that has been associated with 
a procedure in order to take a specific action when an exception condition 
occurs. The VAX Condition Handling Facility searches for condition handlers 
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to handle the exception condition, beginning with the primary exception 
vector of the access mode in which the exception condition occurred. If this 
vector contains the address of a handler, it is called. If the address is zero, 
or if the handler resignals, then the VAX Condition Handling Facility repeats 
the process with the secondary exception vector. Enabling vectored handlers 
is discussed in detail in the VAX/VMS System Services Reference Manual. 
Because the exception vectors are allocated in static storage, they are not 
generally used by modular procedures. 

If neither the primary nor secondary vectored handlers handle the exception 
condition by continuing program execution, then the VAX Condition 
Handling Facility looks for stack frame condition handlers. It looks for the 
address of a condition handler in the first longword of the procedure stack 
frame where the exception condition occurred. At this point, several actions 
are possible, depending on the contents of the first longword: 

• If the address is zero, then this procedure has not set up a condition 
handler. In this case, the VAX Condition Handling Facility continues the 
stack scan by moving to the previous stack frame (that is, the stack frame 
of the calling procedure). 

• If the address is not zero, then a condition handler is present. The VAX 
Condition Handling Facility then calls this handler, which may resignal, 
continue, or unwind (see Section 7.1.4.2). 

The VAX Condition Handling Facility searches for and calls condition 
handlers from each frame on the stack until the frame pointer is zero 
(indicating the end of the call sequence). In that case, the VAX Condition 
Handling Facility calls the vectored catch-all handler, which displays an 
error message and causes the program to exit. Note that normally the frame 
containing the stack catch-all handler is the end of the calling sequence or the 
bottom of the stack. Section 7.1.4 explains the possible actions of default and 
user condition handlers in more detail. 

Figure 7-2 illustrates a stack scan for condition handlers in which the main 
program calls Procedure A, which then calls Procedure B. A stack scan is 
initiated when a hardware exception condition occurs or a call is made to 
LIB$SIGNAL or LIB$STOP. 
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Figure 7-2 Sample Stack Scan for Condition Handlers 
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7.1.3.1 Signal Argument Vector 

The signal argument vector contains all of the information describing the 
nature of the hardware or software condition. Figure 7-3 illustrates the 
open-ended structure of the signal argument vector, which can be from 3 to 
257 longwords in length: 

Figure 7-3 Format of the Signal Argument Vector 


MACRO and BLISS 


n = additional longwords CHF$I—SIG—ARGS 

Condition value CHF$I—SIG—NAME 

Optional additional 
arguments making up one 
or more message sequences 

PC 

PSL 


High-Level Languages 

SIGARGS(I) 

SIGARGS(2) 


SIGARGS(n) 
SIGARGS(n +1) 
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Fields of the Signal Argument Vector 
SIGARGS(I) 

An unsigned integer (n) designating the number of longwords that follow in 
the vector, including PC and PSL. For example, the first entry of a 4-longword 
vector would contain a 3. 

SIGARGS(2) 

A condition value indicating the condition being signaled. Handlers should 
always check to see if the condition is the one that they expect by examining 
the STS$V_COND_ID field of the condition value (bits 27:3). Bits 2:0 are the 
severity field. Bits 31:28 are control bits; they may have been changed by an 
intervening handler and so should not be included in the comparison. You 
can use the Run-Time Library procedure LIB$MATCH_COND to match the 
correct fields. If the condition is not expected, the handler should resignal by 
returning FALSE (bit 0 = 0). 

SIGARGS(3 to n—1) 

Optional arguments that provide additional information about the condition. 
These arguments consist of one or more message sequences. The format of a 
message sequence is described in Section 7.1.5. 
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SIGARGS(n) 

The Program Counter (PC) of the next instruction to be executed if any 
handler (including the system-supplied handlers) returns with the status 
SS$_CONTINUE. For hardware faults, the PC is that of the instruction 
that caused the fault. For hardware traps, the PC is that of the instruction 
following the one that caused the trap. For conditions signaled by calling 
LIB$SIGNAL or LIB$STOP, the PC is the location following the CALLS 
or CALLG instruction. See the VAX-11 Architecture Reference Manual for a 
detailed description of faults and traps. 

SIGARGS(n+1) 

The Processor Status Longword (PSL) of the program at the time that the 
condition was signaled. See the VAX-11 Architecture Reference Manual for 
more about the Processor Status Longword. 

Note: LIB$SIGNAL and LIB$STOP copy the variable-length argument list 
passed by the caller. Then, before calling a condition handler, they 
append the PC and PSL entries to the end of the list. 

The formats for some conditions signaled by the operating system and the 
Run-Time Library are shown in Figures 7-4 and 7-5. 

Figure 7-4 Signal Argument Vector for the Reserved Operand 
Error Conditions 



Figure 7-5 Signal Argument Vector for RTL Mathematics 
Procedure Errors 
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Additional longwords 
Math condition value 
Number of FAO args 
PC following JSB or CALL 
PC following call to LIB$SIGNAL 
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The caller's PC is the PC following the calling program's JSB or CALL to the 
mathematics procedure that detected the error. The PC is that following the 
call to LIB$SIGNAL. 


7.1.3.2 Mechanism Argument Vector 

The mechanism argument vector contains all of the information describing 
the state of the process at the time of the hardware or software signaled 
condition. Figure 7-6 illustrates a mechanism argument vector, which is a 
5-longword vector. 

Figure 7-6 Format of a Mechanism Argument Vector 


MACRO and BLISS 



CHF$I_MCH-ARGS 

CHF$I_MCH-FRAME 

CHF$L_MCH_DEPTH 

CHF$I_MCFI-SAVRO 
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High-Level Languages 

MCHARGS(I) 

MCHARGS(2) 
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MCHARGS(4) 

MCHARGS(5) 
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Fields of the Mechanism Argument Vector 
MCHARGS(I) 

An unsigned integer indicating the number of longwords that follow in the 
vector. Currently, this is always four. 

MCHARGS(2) 

The address of the stack frame of the procedure that established the handler 
being called. This address can be used as a base from which to reference the 
local stack-allocated storage of the establisher, as long as the restrictions on 
the handler's use of storage are observed (see Section 7.2.2). 

MCHARGS(3) 

The stack depth, which is the number of stack frames between the establisher 
of the condition handler and the frame in which the condition was signaled. 
In order that calls to LIB$SIGNAL and LIB$STOP appear as similar as 
possible to hardware exception conditions, the call to LIB$SIGNAL or 
LIB$STOP is not included in the depth. 

If the procedure that contained the hardware exception condition or called 
LIB$SIGNAL or LIB$STOP also handled the exception condition, then the 
depth is zero; if the exception condition occurred in a called procedure and 
its caller handled the exception condition, then the depth is 1; and so on. If 
a system service signals an exception condition, a handler established by the 
immediate caller is entered with a depth of 1. 
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The depth is -2 for a handler established using the primary exception vector, 
-1 for the secondary vector, and -3 for the last-chance vector. 

MCHARGS(4) and MCHARGS(5) 

Copies of the contents of registers RO and R1 at the time of the exception 
condition or the call to LIB$SIGNAL or LIB$STOP. When execution continues 
or a stack unwind occurs, these values are restored to RO and Rl. Thus a 
handler can modify these values to change the function value returned to a 
caller. 



7.1.4 Condition Handlers 

When a procedure is activated, the first longword in its stack frame is 
set to zero. This longword is reserved to contain an address pointing to 
another procedure called the condition handler. If an exception condition 
is signaled during the execution of the procedure, the VAX Condition 
Handling Facility uses the address in the first longword of the frame to call 
the associated condition handler. The arguments passed to the condition 
handling procedure are the signal and mechanism argument vectors described 
in Sections 7.1.3.1 and 7.1.3.2. 

There are various types of condition handlers that can be called for a given 
procedure: 

• User-supplied condition handlers 

You can write your own condition handler and set up its address in the 
stack frame of your procedure using the Run-Time Library procedure 
LIB$ESTABLISH or mechanism supplied by your language. 

• Language supplied condition handlers 

Many high-level languages provide a means for setting up handlers that 
are global to a single procedure. For example, BASIC's ON ERROR 
GOTO and PL/I's ON statement provide language-specific condition 
handlers. If your language provides a condition handling mechanism, 
you should always use it. If you also try to establish a condition handler 
using LIB$ESTABLISH, the two methods of handling exception conditions 
conflict, and the results are unpredictable. 

• System default condition handlers 

VAX/VMS provides a set of default condition handlers. These take over 
if there are no other condition handler addresses on the stack, or if all the 
previous condition handlers have passed on (resignaled) the indication of 
the exception condition. 

Note: Do not use LIB$ESTABLISH to set up a condition handler in a language 
that defines its own condition handling, such as BASIC, COBOL, and 
PL/I. 


7-13 






Condition Handling Procedures 

An Overview of the VAX Condition Handling Facility 


7.1.4.1 Default Condition Handlers 

VAX/VMS establishes the following default condition handlers each time a 
new image is started. The default handlers are shown in the order they are 
encountered when VAX/VMS processes a signal. These three handlers are 
the only handlers that should output error messages. 

• Traceback handler 

The traceback handler is established on the stack after the catch-all 
handler. This enables the traceback handler to get control first. This 
handler performs three functions in the order shown: 

1 Outputs an error message using the Put Message ($PUTMSG) system 
service. $PUTMSG formats the message using the Formatted ASCII 
Output ($FAO) system service and sends the message to the devices 
SYSSERROR and SYS$OUTPUT (if it differs from SYS$ERROR). 

2 Issues a symbolic traceback which shows the state of the procedure 
stack at the time of the exception condition. 

3 Decides whether to continue execution of the image or to force an exit 
based on the severity field of the condition value. 


Severity 

Error Type 

Action 

1 

SUCCESS 

Continue 

3 

INFO 

Continue 

0 

WARNING 

Continue 

2 

ERROR 

Continue 

4 

SEVERE 

Exit 


You can eliminate the traceback handler at link time by using the 
/NOTRACEBACK qualifier in the link command. 

• Catch-all handler 

VAX/VMS establishes the catch-all handler in the first stack frame 
and thus calls it last. This handler performs the same functions as the 
traceback handler, except for the stack traceback. That is, it issues an error 
message and decides whether to continue execution. It is called only if 
you link with the /NOTRACEBACK qualifier. 

• Last-chance handler 

VAX/VMS establishes the last-chance handler with a system exception 
vector. In most cases, this vector contains the address of the catch-all 
handler, so that these two handlers are actually the same. The last-chance 
handler is called only if the stack is invalid or all the handlers on the 
stack have resignaled. If the debugger is present, the debugger's own 
last-chance handler will replace the system last-chance handler. 
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7.1.4.2 Possible Condition Handler Actions 

When a condition handler returns control to the VAX Condition Handling 
Facility, the VAX Condition Handling Facility takes one of the following three 
actions, depending on the value returned by the condition handler. 

• Resignal the condition RO = SS$—RESIGNAL or RO <0> = 0 . 

When a condition handler resignals, it passes control back to the VAX 
Condition Handling Facility with a status code of SS$_RESIGNAL. This 
indicates that the handler was unable to deal with the particular exception 
condition, and it is passing the indication on to other handlers. A handler 
can alter the severity of the signal before resignaling. 

Section 7.2.2.2 contains more information about resignaling. 

• Continue from the point of the signal (RO = SS$_CONTINUE or 
RO <0> = 1). 

When a condition handler returns the status SS$_CONTINUE, the 
VAX Condition Handling Facility returns control to the procedure that 
signaled the exception condition, beginning at the instruction that initiated 
signaling (in the case of faults) or at the instruction following the one 
that initiated signaling (in the case of traps). A condition handler cannot 
continue if the exception condition was signaled by calling LIB$STOP. 

Section 7.2.2.1 contains more information about continuing. 

• Unwind the call stack and dismiss the signal. 

When a condition handler has already called $UNWIND, any return status 
from the condition handler is ignored by the VAX Condition Handling 
Facility. The VAX Condition Handling Facility now unwinds the stack. 

Unwinding the procedure call stack removes call frames, starting with the 
frame in which the condition occurred, and returns control to an earlier 
procedure in the calling sequence. You can unwind the stack whether 
the condition was detected by hardware or signaled using LIB$SIGNAL 
or LIB$STOP. Unwinding is the only way to continue execution after a 
call to LIB$STOP. A condition handler unwinds by calling the Unwind 
($UNWIND) system service. 

Section 7.2.23 shows how to write a condition handler that unwinds the 
call stack. 


7.1.4.3 Interaction Between Default and User-Supplied Handlers 

Several results are possible after a procedure signals, depending on several 
factors, such as the severity of the error, the method of generating the signal, 
and the action of the condition handlers you have defined and the default 
handlers. Given the severity of the condition and the method of signaling. 
Table 7-2 lists all combinations of interaction between user condition 
handlers and default condition handlers. 
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Table 7-2 Interaction Between Handlers and Default Handlers 


Severity 

of 

condition 

User 

handler 

specifies 

CONTINUE 

User 

handler 

specifies 

UNWIND 

Default 

handler 

gets 

control 

No handler 
found 
(bad stack) 

Exception condition is signaled by a call to LIB$SIGNAL or 
detected by hardware 

WARNING, 
INFO, or 
ERROR 

RETURN 

UNWIND 

Issue 

condition 

message 

RETURN 

Call last- 

chance 

handler 

EXIT 

SEVERE 

RETURN 

UNWIND 

Issue 

condition 

message 

Call last- 

chance 

handler 




EXIT 

EXIT 

Exception condition is 

signaled by a call to LIB$STOP 

LIB$STOP 

forces 

severity 

to 

SEVERE 

Message: 
"Attempt to 
continue 
from stop" 

EXIT 

UNWIND 

Issue 

condition 

message 

EXIT 

Call last- 

chance 

handler 

EXIT 
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Displaying Messages 

The standard format for a VAX/VMS message is as follows: 

%FACILITY-L-IDENT, message-text 


FACILITY 

L 

IDENT 

message-text 


Abbreviated name of the software component that issued the 
message. 

Indicator showing the severity level of the exception condition 
that caused the message. 

Symbol of up to nine characters representing the message. 
Brief definition of the cause of the message. 


The message can also include up to 255 formatted-ASCII-output (FAO) 
arguments. These arguments can be used to display variable information 
about the condition that caused the message. In the following examples, the 
file specification is an FAO argument. 

%TYPE-W-OPENIN, error opening __DBO:[FOSTER]AUTHOR.DAT; as input 

Signaling provides a consistent and unified method for displaying messages. 
This subsection describes how the VAX Condition Handling Facility translates 
the original signal into a human-readable message. 
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When any software detects an exception condition, it signals the exception 
condition to the user by calling LIB$SIGNAL or LIB$STOP. The signaling 
procedure passes a signal argument list to these Run-Time Library procedures. 
This signal argument list is made up of the condition value and a set of 
optional arguments that provide information to condition handlers. Signaling 
is used to signal exception conditions generated by DIGITAL-supplied 
software. 

You can use the signaling mechanism to signal messages specific to your 
application. Further, you can chain your own message onto a system 
message. For more information, see Section 7.2.4. 

LIB$SIGNAL and LIB$STOP copy the signal argument list and use it to create 
the signal argument vector. The signal argument vector serves as part of the 
input to the user-established handlers and the system default handlers. 

If all intervening handlers have resignaled, the system default handlers take 
control. The system-supplied default handlers are the only handlers that 
should actually issue messages, whether the exception conditions are signaled 
by DIGIT AL-supplied software or your own programs. That is, a procedure 
should signal exception conditions, rather than issuing its own messages. In 
this way, other applications can call the procedure and override its signal in 
order to change the messages. Further, this technique makes the choice of 
formatting details and wording centralized and consistent. 

The system default handlers pass the signal argument vector to the Put 
Message ($PUTMSG) system service. $PUTMSG formats and displays the 
information in the signal argument vector. 

$PUTMSG performs the following steps: 

1 Interprets the signal argument vector as a series of one or more message 
sequences. Each message sequence starts with a 32-bit, system-wide 
condition value that identifies a message in the system message file. 

2 Obtains the text of the message using the Get Message ($GETMSG) 
system service. The message text definition is actually a SYS$FAO 
control string. It may contain embedded FAO (formatted ASCII output) 
directives. These directives determine how the FAO arguments in the 
signal argument vector are formatted. (See the $FAO system service in the 
VAX/VMS System Services Reference Manual.) 

3 Calls $FAO to format the message, substituting the values from the signal 
argument list. 

4 Issues the message on device SYS$OUTPUT. If SYS$ERROR is different 
from SYS$OUTPUT, and the severity field in the condition value is not 
SUCCESS, $PUTMSG also issues the message on device SYSSERROR. 

The VAX/VMS System Services Reference Manual describes $PUTMSG in 
detail. 

Each message sequence in the signal argument list produces one line of 
output. Figure 7-7 illustrates the three possible message sequence formats. 
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Figure 7-7 Formats of Message Sequences 


No FAO (Formatted ASCII Output) arguments 

Condition value 


Note that a condition value of 
zero results in no message. 


Variable number of FAO arguments 



Condition value 
Number of FAO arguments 


VAX-11 RMS error with STV (Status Value) 

Condition value 

One FAO argument or 
SS$... condition value 

ZK-1967-84 


VAX-11 RMS Condition Value (STS) 


Associated status value (STV) 


VAX RMS system services return two related completion values, the 
completion code and the associated status value. The completion code is 
returned in RO, using the function value mechanism. The same value is also 
placed in Completion Status Code field of the VAX RMS File Access Block or 
Record Access Block associated with the file (FAB$L_STS or RAB$L_STS). 
The status value is returned in the Status Value field of the same FAB or RAB 
(FAB$L_STV or RAB$L_STV). The meaning of this secondary value is based 
on the corresponding STS (Completion Status Code) value. Its meaning could 
be any of the following: 

• An operating system condition value of the form SS$_ 

• A VAX RMS value, such as the size of a record which exceeds the buffer 

• Zero 

Rather than have each calling program determine the meaning of the STV 
value, $PUTMSG performs the necessary processing. Therefore, this STV 
value must always be passed in place of the FAO argument count. In other 
words, a VAX RMS message sequence always consists of two arguments 
(passed by immediate value): an STS value and an STV value. 
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7.1.6 Multiple Active Signals 

A signal is said to be active until the procedure that signaled regains control 
or until the stack is unwound or the image exits. A second signal can occur 
while a condition handler or a procedure it has called is executing. This 
situation is called multiple active signals. When this situation occurs, the 
stack scan is not performed in the usual way. Instead, the frames that were 
searched while processing all of the previous exception conditions are skipped 
when the current exception condition is processed. This is done in order to 
avoid recursively reentering a procedure which is not reentrant. For example, 
FORTRAN code is typically not recursively reentrant. If a FORTRAN handler 
were called while another activation of that handler was still going, the 
results would be unpredictable. 

The modified search procedure can best be illustrated with an example. 
Assume the following calling sequence: 

1 Procedure A calls procedure B, which calls procedure C. 

2 Procedure C signals an exception condition (signal S), and the handler for 
procedure C (CH) resignals. 

3 Control passes to BH, the handler for procedure B. The call frame for 
handler BH is located on top of the signal and mechanism arrays for 
signal S. The saved frame pointer in the call frame for BH points to the 
frame for procedure C. 

4 BH calls procedure X; procedure X calls procedure Y. 

5 Procedure Y signals a second exception condition (signal T). Figure 7-8 
illustrates the stack contents after the second exception condition is 
signaled. 

Figure 7-8 Stack After Second Exception Condition is Signaled 



Normally, the VAX Condition Handling Facility would search all the 
currently active frames for condition handlers, including B and C. If this 
happened, however, BH would be called again. At this point, then, you 
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wish to skip the condition handlers that have already been called. Thus, 
the search for condition handlers should proceed in the following order: 

YH 

XH 

BHH (the handler for procedure B's handler) 

AH 

6 The search now continues in its usual fashion. The VAX Condition 
Handling Facility examines the primary and secondary exception vectors, 
then frames Y, X, and BH. Thus handlers YH, YH, and BHH are called. 
Assume that these handlers resignal. 

7 The VAX Condition Handling Facility now skips the frames that have 
already been searched and resumes the search for condition handlers in 
procedure A's frame. The depths that are passed to handlers as a result of 
this modified search are 0 for YH, 1 for XH, 2 for BHH, and 3 for AH. 

Because of the possibility of multiple active signals, you should be careful 
if you use an exception vector to establish a condition handler. Vectored 
handlers are called, not skipped, each time an exception occurs. 


7.2 Using the VAX Condition Handling Facility 

This section shows you how to build condition handling into your program. 
This process involves one or more of the following steps: 

• Establishing the handler in the stack frame of your procedure 

• Writing a condition handling procedure or choosing one of the Run-Time 
Library procedures that handles exception conditions 

• Including a call to a Run-Time Library signal generating procedure 

• Using the message utility to define your own exception conditions 

• Including a call to the $PUTMSG system service to modify or log the 
system error message 


7.2.1 Establishing a Condition Handler 

A condition handler is established when its address has been placed in 
the first longword of the stack frame of the procedure with which it is to 
be associated. To establish a condition handler, call the Run-Time Library 
procedure LIB$ESTABLISH, using the name of the handler as an argument. 
LIB$ESTABLISH returns as a function value the address of the former handler 
established for the procedure or zero if no handler existed. Some languages 
provide a mechanism for setting up a condition handler. If so, use the 
language mechanism rather than LIB$ESTABLISH. 

The new condition handler remains in effect for your procedure until you call 
LIB$REVERT or control returns to the caller of the caller of LIB$ESTABLISH. 
Once this happens, you must call LIB$ESTABLISH again if the same (or a 
new) condition handler is to be associated with the caller of LIB$ESTABLISH. 

The Run-Time Library provides several condition handlers and procedures 
that a condition handler can call. These procedures take care of several 
common exception conditions. Section 7.3 describes these procedures. 
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7.2.2 Writing a Condition Handler 

You can write a condition handler to take action when an exception condition 
is signaled. When the exception condition occurs, the VAX Condition 
Handling Facility sets up the signal argument vector and mechanism 
argument vector and begins the search for a condition handler. Therefore, 
your condition handling procedure must declare variables to contain the two 
argument vectors. Further, the handler must indicate the action to be taken 
when it returns to the VAX Condition Handling Facility. The handler uses 
its function value to do this. Thus, the calling sequence for your condition 
handler has the following format: 

handler signal-args ,mechanism-args 

signal-args 

The address of a vector of longwords indicating the nature of the condition. 
See Section 7.1.3.1, Signal Argument Vector, for a detailed description. 

mechanism-args 

The address of a vector of longwords that indicate the state of the process at 
the time of the signal. See Section 7.1.3.2, Mechanism Argument Vector, for 
more details. 

result 

A condition value. Success (bit 0 = 1) causes execution to continue at the 
PC and failure (bit 0 = 0) causes the condition to be resignaled. That is, the 
system resumes the search for other handlers. If the handler calls the Unwind 
($UNWIND) system service, the return value is ignored and the stack is 
unwound. See Section 7.2.2.3. 

Handlers can modify the contents of either the signal-args vector or the 
mechanism-args vector. 

In order to protect compiler optimization, a condition handler and any 
procedures that it calls can only reference arguments explicitly passed to 
handlers. They cannot reference COMMON or other external storage, nor 
can they reference local storage in the procedure that established the handler, 
unless the compiler considers the storage to be volatile. Compilers that do 
not adhere to this rule must ensure that any variables referenced by the 
handler are always kept in memory, not in a register. 

As mentioned previously, a condition handler can take one of three actions: 

• Continue execution 

• Resignal the exception condition and resume the stack scanning operation 

• Call $UNWIND to unwind the call stack to an earlier frame 

The sections that follow show how to write condition handlers to perform 
these three operations. 
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7.2.2.1 Continuing 

To continue execution from the instruction following the signal, with no 
error messages or traceback, the handler returns with the function value 
SS$_CONTINUE (bit 0 = 1). If, however, the condition was signaled with a 
call to LIB$STOP, the SS$_CONTINUE return status causes an error message 
(ATTEMPT TO CONTINUE FROM STOP) and the image exits. The only 
way to continue from a call to LIB$STOP is for the condition handler to 
request a stack unwind. 

If execution is to continue after a hardware fault (such as a reserved operand 
fault), the condition handler must correct the cause of the condition before 
returning the function value SS$_CONTINUE or requesting a stack unwind. 
Otherwise, the instruction that caused the fault will be executed again. 

Note: On most VAX machines, hardware floating-point traps have been changed 
to hardware faults. If you still wish floating-point exception conditions 
to be treated as traps, use LIB$SIM_TRAP to simulate the action of 
floating-point traps. (See Section 7.3.1.) 


7.2.2.2 Resignaling 

Condition handlers check for specific errors. If the signaled condition is 
not one of the expected errors, the handler resignals. That is, it returns 
control to the VAX Condition Handling Facility with the function value 
SS$_RESIGNAL (with bit 0 clear). To alter the severity of the signal, the 
handler modifies the low three bits of the condition value and resignals. 

For an example of resignaling, see Section 7.1.6. 


7.2.2.3 Unwinding the Call Stack 

A condition handler can dismiss the signal by calling the system service 
$UNWIND. The stack unwind is initiated when a condition handler that has 
called $UNWIND returns to VAX Condition Handling Facility. Unwinding 
the procedure call stack removes call frames and returns control to the 
procedure specified in the depth argument of $UNWIND. You can unwind 
the stack whether the condition was detected by hardware or signaled by 
LIB$SIGNAL or LIB$STOP. Unwinding is the only way to continue execution 
after a call to LIB$STOP. 

Normally, when a condition handler dismisses the signal, control is returned 
to the establisher or caller of the establisher of the condition handler and 
normal execution resumes. 

Your condition handler unwinds by calling the Unwind ($UNWIND) system 
service. The VAX/VMS System Services Reference Manual describes $UNWIND 
in detail. The Program Counter (PC) of the continuation point may also be 
specified to the $UNWIND service. 

When a condition handler calls $ UNWIND and returns to the VAX Condition 
Handling Facility, the return status is ignored and the following actions occur: 

1 The VAX Condition Handling Facility scans each call frame in the call 
stack, beginning with the one in which the condition occurred, to see if a 
condition handler has been established. 

2 If a handler has been established, the VAX Condition Handling Facility 
calls it, placing the value SS$_UNWIND in the condition value field of the 
signal argument vector. This indicates that the stack is being unwound. 


7-22 








Condition Handling Procedures 

Using the VAX Condition Handling Facility 


3 The handler performs the cleanup operations required by the procedure 
that established it. For example, the handler should deallocate any 
processwide resources that have been allocated. Then, the handler returns 
control to the VAX Condition Handling Facility. 

4 After control returns to VAX Condition Handling Facility or if there is 
no handler established for the procedure, the procedure's stack frame is 
removed from the stack. 

5 When a condition handler is called during the unwinding operation, the 
condition handler must not generate a new signal. A new signal would 
result in unpredictable behavior. 

The number of frames removed depends on the arguments passed to 
$UNWIND. 

• If both arguments are omitted, the stack is unwound to the caller of the 
procedure that established the handler. 

1 Procedure A calls Procedure B. 

2 Procedure B establishes Handler C. 

3 An exception condition occurs during the execution of Procedure B. 

4 The VAX Condition Handling Facility calls Handler C. 

5 Handler C calls $UNWIND with no arguments and returns. 

A call to $UNWIND which contains no depth argument is a request by 
the handler to unwind to the caller of its establisher once the handler 
returns. Therefore, when handler C returns, handler C is called again 
with a SS$_UNWIND condition code. When handler C returns, the 
call frame for procedure B is removed and control is resumed at the 
point of call to procedure B at procedure A. 

• If the first argument depth is specified, this argument specifies the number 
of frames to be removed. 

• If the second argument new-PC is specified, it indicates the address of the 
instruction to which control will return after the unwind. 

An unwind to the caller of the establisher of the condition handler causes 
the frame of the procedure that established the handler to be unwound. In 
this case, the handler will be called twice: once when the VAX Condition 
Handling Facility calls it to handle the raised condition, and again when the 
frame in which the handler is established is removed. In the example above, 
handler C is called twice. 

Handlers established by the primary, secondary, or last-chance vectors are 
not called, since they are not removed during an unwind operation. 

While it is unwinding the stack, the VAX Condition Handling Facility ignores 
any function value returned by a condition handler. For this reason, a handler 
cannot both resignal and unwind. Thus, the only way for a handler to both 
issue a message and perform an unwind is to call LIB$SIGNAL and then call 
$UNWIND. If your program calls $UNWIND before calling L1B$SIGNAL, the 
result is unpredictable. 

When the VAX Condition Handling Facility calls the condition handler 
established for each frame during unwind, the call is of the standard form, 
described in Section 7.2.1. The arguments passed to the condition handler 
(the signal and mechanism argument vectors) are shown in Figure 7-9. 
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Figure 7-9 Arguments Passed to Condition Handler During 
Unwind 



If the handler is to specify the function value of the last function to be 
unwound, it should modify the saved copies of RO and R1 (CHF$L__MCH_ 
SAVRO and CHF$L_MCH_SAVR1) in the mechanism argument vector. RO 
and R1 are restored from the mechanism argument vector at the end of the 
unwind. 


7.2.3 Generating Signals 

When software detects an exception condition, it normally calls one of the 
Run-Time Library signal-generating procedures: LIB$SIGNAL or LIB$STOP, 
to initiate the signaling mechanism. This call indicates to the calling program 
that the exception condition has occurred. Your program can also call one of 
these procedures explicitly to indicate an exception condition. Furthermore, 
some languages have built-in methods for signaling errors specific to the 
language. 

When your program wants to issue a message and allow execution to 
continue after handling the condition, it calls the standard procedure, 
LIB$SIGNAL. The calling sequence for LIB$SIGNAL is: 

LIB$SIGNAL condition-valuel [.numberl] [,FAO-argl...,FA0-argnl] 

[,condition-value2] [,number2] [,FA0-arg2...,FA0-argn2] 

Only the condition-valuel argument must be specified; other arguments are 
optional. The numberl argument, if specified, contains the number of FAO 
arguments that will be associated with condition-valuel. The condition- 
value2 argument is optional; it may be specified with or without the number2 
or FAO-arg2 arguments. The number2 argument, if specified, contains the 
number of FAO arguments that will be associated with condition-value2. 
You may specify condition-value3, condition-value4, condition-value5, and 
so on, along with their corresponding number and FAO arguments. 
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For further information about the arguments to LIB$SIGNAL, refer to the 
description of LIB$SIGNAL in Part II of this manual. 

condition-value 

type: longword (unsigned) 
access: read only 
mechanism: by value 

VAX 32-bit condition value. The condition-value argument is an unsigned 
longword that contains this condition value. Section 7.1.2 explains the format 
of a VAX condition value. 

number 

type: longword integer (signed) 
access: read only 
mechanism: by value 

Number of FAO arguments associated with the condition value. The number 
argument is a signed longword integer that contains this number. If omitted 
or specified as zero, no FAO arguments follow. 

The maximum number of FAO arguments specified must not exceed 253. See 
Sections 7.1.5 and 7.2.4 for more information about FAO arguments. 

FAO-arg(s) 

type: unspecified 
access: read only 
mechanism: by value 

Additional FAO (formatted ASCII output) argument(s) which are associated 
with the specified condition value. The FAO-arg(s) argument is the address 
of a signed longword integer or a character string that contains these 
additional FAO arguments. Section 7.1.5 explains the message format. 

When your program wants to issue a message and stop execution 
unconditionally, it calls LIB$STOP. The calling sequence for LIBSSTOP 
is as follows: 

LIB$STOP condition-valuei [.numberl] [,FAO-argi...,FA0-argnl] 

[,condition-value2] [,number2] [,FA0-arg2...,FA0-argn2] 

Only the condition-valuei argument must be specified; other arguments are 
optional. The numberl argument, if specified, contains the number of FAO 
arguments that will be associated with condition-valuei. The condition- 
value2 argument is optional; it may be specified with or without the number2 
or FAO-arg2 arguments. The number2 argument, if specified, contains the 
number of FAO arguments that will be associated with condition-value2. 
You may specify condition-value3, condition-value4, condition-value5, and 
so on, along with their corresponding number and FAO arguments. 

For further information about the arguments to LIB$STOP, refer to the 
description of LIB$STOP in Part II of this manual. 

In both cases, condition-value indicates the condition that is being signaled. 
However, LIB$STOP always sets the severity of condition-value to SEVERE 
before proceeding with the stack-scanning operation. 
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The FAO arguments describes the details of the exception condition. These 
are the same arguments that are passed to the VAX Condition Handling 
Facility as part of the signal argument vector. The system default condition 
handlers pass them to $PUTMSG, which uses them to issue a system 
message. 

Unlike most procedures, LIB$SIGNAL and LIB$STOP preserve RO and R1 
as well as the other registers. Therefore, a call to LIB$SIGNAL allows the 
debugger to display the entire state of the process at the time of the exception 
condition. This is useful for debugging checks and gathering statistics. 

The behavior of LIB$SIGNAL is the same as that of the exception dispatcher 
that performs the stack scan after hardware detects an exception condition. 
That is, the system scans the stack in the same way and the same arguments 
are passed to each condition handler. This allows a user to write a single 
condition handler to detect both hardware and software conditions. 


7.2.4 Signaling User-Defined Messages 

Section 7.1.5 explains how the VAX Condition Handling Facility displays 
messages. The signal argument list passed to LIB$SIGNAL or LIB$STOP 
can be seen as one or more message sequences. Each message sequence 
consists of a condition value, an FAO count, which specifies the number of 
FAO arguments to come, and the FAO arguments themselves. (The FAO 
count is omitted in the case of SYSTEM and RMS messages.) The message 
text definition itself is actually a SYS$FAO control string, which may have 
embedded $FAO directives. The VAX/VMS System Services Reference Manual 
describes the Formatted ASCII Output ($FAO) system service in detail. 

The VAX/VMS Message Utility is provided for compiling message sequences 
specific to your application. When you have defined an exception condition 
and used the VAX/VMS Message Utility to associate a message with that 
exception condition, your program can call LIB$SIGNAL or LIB$STOP to 
signal the exception condition. Then the system default condition handlers 
will display your error message in the standard VAX/VMS format. 

To use the message utility, follow these steps: 

1 Create a source file that specifies the information used in messages, 
message codes, and message symbols. 

2 Use the MESSAGE command to compile this source file. 

3 Link the resulting object module, either by itself or with another object 
module containing a program. 

4 Run your program so that the messages are accessed, either directly or 
through the use of pointers. 

See the description of the VAX/VMS Message Utility in the VAX/VMS 
Utilities Reference Volume. 

You signal a message that is defined in a message source file by calling 
LIB$SIGNAL or LIB$STOP, as for any software-detected exception condition. 


A signal argument list may contain one or more condition values and FAO 
arguments. Each condition value and its FAO arguments is "chained" to the 
next condition value and its FAO arguments. You can use chained messages 
to provide more specific information about the exception condition being 
signaled, along with a general message. 
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The following message source file defines an exception condition 

PROG_FAIGETMEM: 

.FACILITY PROG,1 /PREFIX=PROG__ 

.SEVERITY FATAL 

.BASE 100 

FAIGETMEM <failed to get !UL bytes of memory>/FAO_COUNT=l 

.END 

This source file sets up the exception message as follows: 

• The .FACILITY directive specifies the facility, PROG, and its number, 1. It 
also adds the /PREFIX to determine the prefix to be used in the message. 

• The .SEVERITY directive specifies that PROG_FAIGETMEM is a fatal 

exception condition. That is, the SEVERITY field in the condition value 
for PROG_FAIGETMEM is set to SEVERE (bits 0:3 = 4). 

• The BASE directive specifies that the condition identification numbers in 
the PROG facility will begin with 100. 

• FAIGETMEM is the symbol name. This name is combined with the 
prefix defined in the facility definition to make the message symbol. The 
message symbol becomes the symbolic name for the condition value. 

• The text in angle brackets is the message text. This is actually a SYS$FAO 
control string. When $PUTMSG calls the $FAO system service to format 
the message, $FAO includes the FAO argument from the signal argument 
vector and formats the argument according to the embedded FAO directive 
(!UL). 

• The .END statement terminates the list of messages for the PROG facility. 


7.2.5 Logging Error Messages to a File 

You can write a condition handler to obtain a copy of a system error message 
text and write the message into an auxiliary file, such as a listing file. In this 
way, you can receive identical messages at the terminal (or batch log file) and 
in the auxiliary file. 

To log messages, you must write a condition handler and an action 
subroutine. Your handler calls the Put Message ($PUTMSG) system 
service explicitly. The operation of $PUTMSG is described in Section 7.1.5. 
The handler passes to $PUTMSG the signal argument vector and the address 
of the action subroutine. $PUTMSG passes to the action subroutine the 
address of a string descriptor which contains the length and address of the 
formatted message. The action subroutine can scan the message, copy it into 
a log file, or both. 

It is important to keep the displaying of messages centralized and consistent. 
Thus, you should use only $PUTMSG to display or log system error 
messages. Further, because the system default handlers call $PUTMSG to 
display error messages, your handlers should avoid displaying the error 
messages. There are two ways to do this: 

1 Your handler should not call $PUTMSG directly to display an error 
message. Instead, your handler should resignal the error. This allows 
other calling procedures to change or suppress the message, or recover 
from the error. The system default condition handlers will display the 
message. 
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2 If the action subroutine that you supply to $PUTMSG returns a success 
code, $PUTMSG displays the error message on SYS$OUTPUT or 
SYS$ERROR, or both. Thus, your action routine should process the 
message and then return a failure code, so that $PUTMSG will not display 
the message at this point. 

Figure 7-10 shows the sequence of events involved in calling $PUTMSG to 
log an error message to a file. 

Figure 7-10 Using a Condition Handler to Log an Error Message 


CALL 


Procedure A calls Procedure B 


An exception occurs during Procedure B CHF calls 
Handler B 


Handler B calls $PUTMSG, and passes signal argu¬ 
ment vector and address of action subroutine. 


$PUTMSG obtains error message text, passes one 
line at a time to action subroutine 


Action subroutine logs the line of message text to a 
file. 


RETURN 



Handler B resignals the error. The CHF continues the 
stack scan by calling the handler established for Pro¬ 
cedure A The error message(s) will be displayed by 
the default handlers. 


$PUTMSG returns to Handler B. 


Action subroutine returns FAILURE status to 
SPUTMSG. No error message is displayed. 


ZK-1934-84 


7.3 Run-Time Library Condition Handling Procedures 

The Run-Time Library provides several procedures that can be established 
as condition handlers or called from a condition handler to handle signaled 
exception conditions. This section shows how to use these procedures. 
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• 


7.3.1 

Convert a Floating-Point Fault to a Floating-Point Trap 

A trap is an exception condition that is signaled after the instruction that 
caused it has finished executing. A fault is an exception condition that is 
signaled during the execution of the instruction. When a trap is signaled, 
the PC (Program Counter) in the signal argument vector points to the next 
instruction after the one that caused the exception condition. When a fault 
is signaled, the PC in the signal argument vector points to the instruction 
that caused the exception condition. See the VAX-11 Architecture Reference 
Manual for more information on faults and traps. 

• 

LIB$SIM_TRAP can be established as a condition handler, or called from a 
condition handler, to convert a floating-point fault to a floating-point trap. 

After LIB$SIM_TRAP is called, the PC points to the instruction after the 
one that caused the exception condition. Thus your program can continue 
execution without fixing up the original condition. LIB$SIM_TRAP intercepts 
only floating overflow, underflow, and divide-by-zero faults. 

7.3.2 

Change a Signal to a Return Status 

• 

• 

When it is preferable to detect errors by signaling, but the calling procedure 
expects a returned status, LIB$SIG_TO_RET may be used by the procedure 
that signals. LIB$SIG_TO_RET is a condition handler that converts any 
signaled condition to a return status. The status is returned to the caller 
of the procedure that established LIB$SIG_TO_RET. You may establish 
LIB$SIG_TO_JRET as a condition handler by specifying it in a call to 
LIB$ESTABLISH. 

LIB$SIG_TO_RET may also be called from another condition handler. 
LIB$SIG_TO_RET is called from a condition handler, the signaled condition 
is returned as a function value to the caller of the establisher of that handler 
when the handler returns to the VAX Condition Handling Facility. When a 
signaled exception condition occurs, LIB$SIG__TO_RET procedure does the 
following: 

• Places the signaled condition value in the image of RO that is saved as 
part of the mechanism argument vector. 

• Calls the Unwind ($UNWIND) system service with the default arguments. 
After returning from LIB$SIG_TO_RET (when it is established as a 
condition handler) or after returning from the condition handler that 
called LIB$SIG_TO_RET (when LIB$SIG_TO_RET is called from a 
condition handler), the stack is unwound to the caller of the procedure 
that established the handler. 

Your calling procedure can now test RO, as if the called procedure had 
returned a status, and specify an error recovery action. 

7.3.3 

• 

Change a Signal to a Stop 

LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled 
by a call to LIB$STOP. 

LIB$SIG_TO_STOP may be enabled as a condition handler for a procedure 
or it may be called from a condition handler. When a signal is generated 
by LIB$STOP, the severity code is forced to SEVERE and control cannot 
return to the procedure that signaled the condition. See Section 7.2.2.1 for a 
description of continuing normal execution after a signal. 
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7.3.4 Match Condition Values 

LIB$MATCH_COND checks for a match between two condition values in 
order to allow a program to branch according to the condition found. If no 
match is found, the procedure returns zero. The procedure only matches 
the condition identification field (STS$V_COND_ID) of the condition value; 
it ignores the control bits and the severity field. If the facility-specific bit 
(STS$V_FAC_SP = bit 15) is clear in cond-val (meaning that the condition 
value is system-wide), LIB$MATCH_COND ignores the facility code field 
(STS$V_FAC_NO = bits 27:17) and compares only the STS$V_MSG_ID 
fields (bits 15:3). 


7.3.5 Correct a Reserved Operand Condition 

After a signal of SS$_ROPRAND during a floating-point instruction, 
LIB$FIXUP_FLT finds the operand and changes it from -0.0 to a new value 
or to +0.0. 


7.3.6 Decode the Instruction That Generated a Fault 

LIB$DECODE_FAULT locates the operands for an instruction that caused 
a fault and passes the information to a user action routine. When called 
from a condition handler, LIB$DECODE_FAULT locates all the operands 
and calls an action routine that you supply. Your action routine performs 
the steps necessary to handle the exception condition and returns control to 
LIB$DECODE_FAULT. LIB$DECODE_FAULT then restores the operands 
and the environment, as modified by the action routine, and continues 
execution of the instruction. 


7.4 How Run-Time Library Procedures Handle Exceptions 

Most general-purpose Run-Time Library procedures handle errors by 
returning a status in R0. In some cases, however, exceptions that occur 
during the execution of a Run-Time Library procedure are signaled. This 
section tells how Run-Time Library procedures signal exception conditions. 

Some calls to the Run-Time Library do not or cannot specify an action to be 
taken. In this case, the Run-Time Library will signal the proper exception 
condition using the VAX signaling mechanism. 

In order to maintain modularity, the Run-Time Library does not use exception 
vectors, which are processwide data locations. Thus the Run-Time Library 
itself does not establish handlers using the primary, secondary, or last-chance 
exception vectors. 


7.4.1 Exception Conditions Signaled from Mathematics Procedures 

Mathematics procedures return function values in register R0 or registers 
R0/R1, unless the return values are larger than 64 bits. For this reason, 
mathematics procedures cannot use R0 to return a completion status and 
must signal all errors. In addition, all mathematics routines signal an error 
specific to the MTH$ facility, rather than a general hardware error. 
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7.4.1.1 Integer Overflow and Floating-Point Overflow 

Although the hardware normally detects integer overflow and floating-point 
overflow errors, Run-Time Library mathematics procedures are programmed 
with a software check to trap these conditions before the hardware signaling 
process can occur. This means that they call LIB$SIGNAL, instead of 
allowing the hardware to initiate signaling. 

The software check is needed because JSB routines cannot set up condition 
handlers. The check permits the JSB mathematics procedures to add an extra 
stack frame so that the error message and stack traceback will appear as if 
a CALL instruction had been performed. Because of the software check, JSB 
procedures will not cause a hardware exception condition even when the 
calling program has enabled the detection of integer overflow. On the other 
hand, floating-point overflow detection is always enabled and cannot be 
disabled. 

If an integer or floating-point overflow occurs during a CALL or JSB 
procedure, the procedure signals a mathematics-specific error such as MTH$_ 
FLOOVEMAT (FLOATING OVERFLOW IN MATH LIBRARY) by calling 
LIB$SIGNAL explicitly. 


7.4.1.2 Floating-Point Underflow 

All mathematics procedures are programmed to avoid floating-point 
underflow conditions. Software checks are made to determine if a floating¬ 
point underflow condition would occur. If so, the software makes an 
additional check: 

• If the immediate calling program (CALL or JSB) has enabled floating-point 
underflow traps, a mathematics-specific error condition is signaled. 

• Otherwise, the result is corrected to zero and execution continues with no 
error condition. 

The user can enable or disable floating-point underflow detection at run time 
by calling the procedure LIB$FLT_UNDER. 


7.4.2 Overflow/Underflow Detection Enabling Procedures 

You can use the following Run-Time Library procedures to enable or disable 
the signaling of decimal overflow, floating-point underflow, and integer 
overflow: 

• LIB$DEC_OVER enables or disables the reporting of decimal overflow. 

• LIB$FLT_UNDER enables or disables the reporting of floating-point 
underflow. 

• LIB$INT_OVER enables or disables the reporting of integer overflow. 

You cannot disable the signaling of integer divide-by-zero, floating-point 
overflow, and floating-point or decimal divide-by-zero. 

When the signaling of a hardware condition is enabled, the occurrence of 
the exception condition causes VAX/VMS to signal the condition as a severe 
error. When the signaling of a hardware condition is disabled, the occurrence 
of the condition is ignored and the processor executes the next instruction in 
the sequence. 
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The signaling of overflow and underflow detection is enabled independently 
for each procedure activation, since the call instruction saves the state of 
the calling program's hardware enables in the stack and then initializes the 
enables for the called procedure. A return instruction restores the calling 
program's enables. 

These Run-Time Library procedures are intended primarily for higher-level 
languages, since you can achieve the same effect in MACRO with the single 
Bit Set PSW (BISPSW) or Bit Clear PSW (BICPSW) instructions. 

These procedures allow you to enable and disable detection of decimal 
overflow, floating-point underflow, and integer overflow for a portion of 
your procedure's execution. Note that the BASIC and FORTRAN compilers 
provide a compile-time qualifier that permits you to enable or disable integer 
overflow for your entire procedure. 
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3 Memory Allocation Procedures 


This chapter discusses the Run-Time Library procedures that perform 

dynamic memory allocation functions. 

The topics covered in this chapter include the following: 

• Section 8.1 provides an overview of dynamic memory allocation. 

• Section 8.2 describes procedures for allocating and freeing pages of 
memory. 

• Section 8.3 introduces the concept of zones and describes the procedures 
used to create, delete, and reset zones. 

• Section 8.4 describes the procedures used to allocate and free 
variable-sized blocks of memory. 

• Section 8.5 discusses the different algorithms that can be used to allocate 
memory within a zone. 

• Section 8.6 introduces user-defined zones that can be used to implement 
additional allocation algorithms, or to monitor the behavior of other 
zones. 

• Section 8.7 describes interactions between the Run-Time Library memory 
allocation procedures and high-level language memory allocation facilities, 
as well as interactions with other Run-Time Library procedures. 

• Section 8.8 discusses interactions between the Run-Time Library memory 
allocation procedures and VAX/VMS memory management system 
services. 


8.1 Overview 


Sophisticated software systems must often create and manage complex data 
structures. In these systems, the size and number of elements are not always 
known in advance. You can tailor the memory allocation for these elements 
by using dynamic memory allocation. By managing the memory allocation, 
you can avoid allocating fixed tables that may be too large or too small for 
your program. To help you manage memory, the Run-Time Library and the 
VAX/VMS operating system provide a hierarchy of procedures and services 
for memory management. 
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8.1.1 Virtual Address Space 


The virtual address space of an executing program consists of the following 
three regions: 

1 A process program region 

The process program region is also referred to as PO space. PO space 
contains the instructions and data for the image currently being executed. 

Your program can dynamically allocate storage in the process program 
region by calling Run-Time Library dynamic memory allocation 
procedures or VAX/VMS system services. 

2 A process control region 

The process control region is also referred to as PI space. PI space 
contains system control information and the user-mode process stack. The 
user mode stack expands as necessary toward the lower-addressed end of 
PI space. 

3 A common system region 

The common system region is also referred to as SO space. SO space 
contains the VAX/VMS operating system. Your program cannot allocate 
or free memory within the common system region from the user access 
mode. 

A summary of these regions appears in Figure 8-1. 

Figure 8-1 Virtual Address Overview 
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8.1.2 Memory Allocation Procedures 

Memory allocation procedures allow you to allocate and free storage within 
the virtual address space available to your process. 

This section describes three levels of memory allocation procedures. Those 
levels are as follows: 

1 Memory management system services 

The memory management system services comprise the lowest level of 
memory allocation procedures. These services include, but are not limited 
to, the following: 

$EXPREG (Expand Region) 

$CRETVA (Create Virtual Address Space) 

$DELTVA (Delete Virtual Address Space) 

SCRMPSC (Create and Map Section) 

$MGBLSC (Map Global Section) 

$DGBLSC (Delete Global Section) 

For most cases in which a system service is used for memory allocation, 
the Expand Region system service ($EXPREG) is used to create 512-byte 
pages of virtual memory. 

2 Run-Time Library page management procedures 

The Run-Time Library page management procedures LIB$GET_VM_ 
PAGE and LIB$FREE_VM__PAGE provide a convenient mechanism for 
allocating and freeing pages of memory. 

These procedures maintain a processwide pool of free pages. If no 
unallocated pages are available when LIB$GET_VM_PAGE is called, it 
calls $EXPREG to create the required pages in the program region (PO 
space). 

3 Run-Time Library heap management procedures 

The Run-Time Library heap management procedures LIB$GET_VM and 
LIB$FREE_VM provide a mechanism for allocating and freeing blocks of 
memory of arbitrary size. 

If no unallocated block is available to satisfy a call to LIB$GET_VM, it 
calls LIB$GET_VM__PAGE to allocate additional pages. 

Modular application programs can call procedures in any or all levels of 
the hierarchy, depending on the kinds of services the application program 
needs. The basic rule that must be observed when using multiple levels of 
the hierarchy is as follows: 

• Memory that is allocated by an allocation procedure at one level of 
the hierarchy must be freed by calling a deallocation procedure at the 
same level of the hierarchy. For example, if you allocated a page of 
memory by calling LIB$GET_VM_PAGE, you can free it only by calling 
LIB$FREE_VM_P AGE. 

Figure 8-2 shows the three levels of memory allocation procedures. 
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Figure 8-2 Hierarchy of Memory Management Procedures 
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8.2 Allocating and Freeing Pages 

The Run-Time Library page management procedures LIB$GET_VM_PAGE 
and LIB$FREE_VM_PAGE provide a flexible mechanism for allocating 
and freeing pages of memory. In general, modular procedures should use 
these procedures rather than direct system service calls to manage pages of 
memory. The page management procedures maintain a processwide pool of 
free pages and automatically reuse free pages. If your program calls system 
services directly, it must do the bookeeping to keep track of free pages. 

LIB$GET_VM_PAGE and LIB$FREE_VM_PAGE are fully reentrant. They 
can be called by code running at AST level or in an Ada multitasking 
environment. 

All pages allocated by LIB$GET_VM_PAGE are created with user-mode 
read-write access, even if the call to LIB$GET_VM__PAGE is made from a 
more privileged access mode. 

LIB$GET_VM_PAGE and LIB$FREE_VM_PAGE are designed for request 
sizes ranging from one page to a few hundred pages. If you are using very 
large request sizes (over 1000 contiguous pages in a single request), the 
bitmap allocation method that is used may cause fragmentation of your 
virtual address space. For very large request sizes, you should use direct calls 
to $EXPREG. 

The rules for using LIB$GET_VM_PAGE and LIB$FREE_VM_PAGE are as 
follows: 

• Any memory you free by calling LIB$FREE_VM_PAGE must have 
been allocated by a previous call to LIB$GET_VM_PAGE. You cannot 
allocate memory by calling $EXPREG or $CRETVA and then free it using 
LIB$FREE_VM_PAGE. 
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• All memory allocated by LIB$GET__VM_PAGE is page aligned; that is, 
the low-order 9 bits of the address are all zero. All memory freed by 
LIB$FREE_VM_PAGE must also be page aligned; an error status will be 
returned if you attempt to free a block of memory that is not page aligned. 

• You can free a smaller group of pages than you allocated. That is, 
if you allocated a group of four contiguous pages by a single call to 
LIB$GET_VM_PAGE, you can free the memory by several calls to 
LIB$FREE_VM_PAGE; for example, free one page, two pages, and one 
page. 

• You can combine contiguous groups of pages that were allocated by 
several calls to LIB$GET__VM_PAGE into one group of pages that 
are freed by a single call to LIB$FREE_VM__PAGE. Before doing this, 
however, you must compare the addressses to ensure that the pages you 
are combining are indeed contiguous. Of course, you must ensure that a 
procedure only frees pages that it has previously allocated and that it still 
owns. 

• Be especially careful that you do not attempt to free a set of pages twice. 

It is possible that you may free a set of pages in one procedure and 
reallocate those same pages from another procedure. If the first procedure 
then deallocates those pages a second time, any informaiton that was 
stored in them by the second procedure is lost. Because the pages are still 
allocated to your program (even though to a different procedure) this type 
of programming mistake will not generate an error. 

• The contents of memory allocated by LIB$GET_VM_PAGE are 
unpredictable. Your program must assign values to all locations that it 
uses. 

• You should try to minimize the number of request sizes your program 
uses to avoid fragmentation of the free page pool. This concept is 
explained in Figure 8-3. 

Figure 8-3 Memory Fragmentation 
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The straight line running across Figure 8-3 represents the memory 
allocated to your program. The blocks represent memory that has already 
been allocated. At this point, if you request 16 pages, memory will have 
to be allocated at the far right end of the memory line shown in this 
figure, even though there are 20 free pages before that point. You cannot 
use 16 of these 20 pages because the 20 free pages are 'fragmented' into 
groups of 15, 3, and 2 pages. 

Fragmentation is discussed further in Section 8.3.1. 
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8.3 Zones 


The Run-Time Library heap management procedures LIB$GET—VM and 
LIB$FREE_VM are based on the concept of zones. A zone is a logically 
independent memory pool or subheap; a program may use several zones to 
structure its heap memory management. 

You create a zone with specified attributes by calling the procedure 
LIB$ CREATE—VM—ZONE. LIB$CREATE_VM_ZONE returns a zone-id value 
that you can use in subsequent calls to the procedures LIB$GET_VM and 
LIB$FREE_VM. When you no longer need the zone, you can delete the zone 
and free all the memory it controls by a single call to LIB$DELETE_VM_ 
ZONE. 

If you call LIB$GET_VM to allocate memory from a zone and the zone has 
no free memory to satisfy the request, LIB$GET—VM calls LIB$GET_VM_ 
PAGE to allocate a block of contiguous pages for the zone. Each such block 
of contiguous pages is called an area. You control the number of pages in an 
area by specifying the area extension size attribute when you create the zone. 

The systematic use of zones provides the following benefits: 

• Structuring heap memory management 

Data structures in your program may have different lifetimes or dynamic 
scopes. Some structures may continue to grow during the entire execution 
of your program, while others exist for a very short time and are then 
discarded by the program. You can create a separate zone in which you 
allocate a particular type of short-lived structure. When the program no 
longer needs any of those structures, you can delete all of them in a single 
operation by calling LIB$DELETE_VM—ZONE. 

• Program locality 

Program locality is a characteristic of a program that indicates how close 
or far apart the references to virtual memory are over a period of time. A 
program with a high degree of program locality does not refer to many 
widely scattered virtual addressses in a short period of time. Maintaining 
a high degree of program locality reduces the number of page faults and 
improves program performance. 

It is important to minimize the number of page faults to obtain best 
performance in a virtual memory system like VAX/VMS. For example, 
if your program creates and searches a symbol table, you can reduce the 
number of page faults incurred by the search operation by using as few 
pages as possible to hold all the symbol table entries. If you allocate 
symbol table entries and other items unrelated to the symbol table in 
the same zone, each page of the symbol table will contain both symbol 
table entries and other items. Because of the extra unrelated entries, the 
symbol table will take up more pages than it actually needs. A search of 
the symbol table will then access more pages and performance will be 
lower as a result. You may be able to reduce the number of page faults by 
creating a separate symbol table zone, so that pages that contain symbol 
table entries do not contain any unrelated items. 

• Specialized allocation algorithms 

There is not a single memory allocation algorithm that is ideal for 
all applications. Section 8.5 describes the Run-Time Library memory 
allocation algorithms and their performance characteristics so that you can 
select an appropriate algorithm for each zone that you create. 
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• Performance tuning 

You can specify a number of attributes that affect performance when you 
create a zone. The allocation algorithm you select can have a significant 
effect on performance. By specifying the allocation block size, you can 
improve performance and reduce fragmentation within the zone at the 
cost of some extra memory. Boundary tags can also be used to improve 
the speed of LIB$FREE_VM at the cost of some extra memory. Boundary 
tags are further discussed in Section 8.3.1. 


8.3.1 Zone Attributes 


You can specify a number of zone attributes when you call LIB$CREATE_ 
VM—ZONE to create the zone. The attributes that you specify are permanent; 
that is, you cannot change the attribute values. They remain constant until 
you delete the zone. Each zone that you create can have a different set of 
attribute values. Thus you can tailor each zone to optimize program locality, 
execution time, and memory usage. 

This section describes each of the zone attributes, suggested values for the 
attribute, and the effects of the attribute on execution time and memory 
usage. If you do not specify a complete set of attribute values, LIB$CREATE_ 
VM--ZONE will provide defaults for many of the attributes. More detailed 
information on argument names and the encoding of arguments is given in 
the description of LIB$CREATE—VM_ZONE (see Part II of this manual). 

The zone attributes are as follows: 

• Allocation algorithms 

The Run-Time Library heap management procedures provide four 
algorithms to allocate and free memory, and to manage blocks of free 
memory. The algorithms are listed here. (See Section 8.5 for more 
details.) 

1 The First Fit algorithm (LIB$K_VM_FIRST_FIT) maintains a linked list 
of free blocks, sorted in order of increasing memory address. 

2 The Quick Fit algorithm (LIB$K_VM_QUICK__FIT) maintains a set of 
lookaside lists indexed by request size for request sizes in a specified 
range. For request sizes that are not in the specified range, a First Fit 
list of free blocks is maintained by the heap management procedures. 

3 The Frequent Sizes algorithm (LIB$K_VM_FREQ_SIZES) is similar to 
Quick Fit in that it maintains a set of lookaside lists for some block 
sizes. You specify the number of lists when you create the zone; the 
sizes associated with those lists are determined by the actual sizes of 
blocks that are freed. 

4 The Fixed Size algorithm (LIB$K_VM_FIXED) maintains a single 
queue of free blocks. 

• Boundary-tagged blocks 

You can specify the use of boundary tags (LIB$M_VM_BOUNDARY_ 
TAGS) with any of the algorithms that handle variable-sized blocks. The 
algorithms that handle variable-sized blocks are First Fit, Quick Fit, and 
Frequent Sizes. 
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If you specify boundary tags, LIB$GET_VM appends two additional 
longwords to each block that you allocate. LIB$FREE_JVM uses these tags 
to speed up the process of merging adjacent free blocks on the First Fit 
free list. Using the standard First Fit insertion and merge, the execution 
time and number of page faults to free a block are proportional to the 
number of items on the list; freeing N blocks takes time proportional to 
N squared. When boundary tags are used, LIB$FREE_VM does not have 
to keep the free list in sorted order. This reduces the time and number of 
page faults for freeing one block to a constant value that is independent 
of the number of free blocks. By using boundary tags you can improve 
execution time at the cost of some additional memory for the tags. 

The use of boundary tags can have a significant effect on execution time if 
ALL of the following three conditions are present. 

1 You are using the First Fit algorithm. 

2 There are many calls to LIB$FREE_VM. 

3 The free list is long. 

Boundary tags will not improve execution time if you are using Quick Fit 
or Frequent Sizes and if all the blocks being freed use one of the lookaside 
lists. No merging or searching is done for free blocks on a lookaside list. 

The boundary tags specify the length of each block that is allocated, so 
you do not need to specify the length of a tagged block when you free it. 
This reduces the bookeeping that your program must perform. Figure 8-4 
shows the placement of boundary tags. 

Figure 8-4 Boundary Tags 
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Boundary tags are not visible to the calling program. The request size you 
specify when calling LIB$GET_VM is the number of usable bytes your 
program needs. The address returned by LIB$GET_VM is the address of 
the first usable byte of the block, and that same address is used when you 
call LIB$FREE__VM. 
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• Area extension size 

Pages of memory are allocated to a zone in contiguous groups called 
areas. By specifying area extension parameters for the zone, you can tailor 
the zone to achieve a satisfactory balance between locality, memory usage, 
and execution time for allocating pages. If you specify a large area size, 
you will improve locality for blocks in the zone but you may waste a large 
amount of virtual memory. Pages may be allocated to an area of a zone, 
but the memory might never be used to satisfy a LIB$GET—VM allocation 
request. If you specify a small area extension size, you will reduce the 
number of pages used, but you may reduce locality and you will increase 
the amount of overhead for area control blocks. 

You can specify two area extension size values: an initial size and an 
extend size. If you specify an initial area size, that number of pages will 
be allocated to the zone when you create the zone. If you do not specify 
an initial size, no pages are allocated until the first call to LIB$GET_VM 
that references the zone. When an allocation request cannot be satisfied 
by blocks from the free list or from memory in any of the areas owned 
by the zone, a new area is added to the zone. The size of this area is 
the maximum of the area extend size and the current request size. The 
extend size does not limit the size of blocks you can allocate. If you do 
not specify extend size when you create the zone, a default of 16 pages is 
used. 

You should choose a few area extension sizes and use them throughout 
your program. It is also desirable to choose extension sizes that are 
multiples of each other. Memory for areas is allocated by calling 
LIB$GET—VM—PAGE. You should choose the area extension sizes in 
order to minimize fragmentation. DIGITAL-supplied software generally 
uses extension sizes that are a power of 2. 

You should also consider the overhead for area control blocks when 
choosing the area extension parameters. Each area control block is 64 
bytes long. Table 8-1 shows the overhead for various extension sizes. 


Table 8-1 Overhead for Area Control Blocks 


Area Size (in pages) 

Overhead Percentage 

1 

12.5 % 

2 

6.3 % 

4 

3.1 % 

16 

0.8 % 

128 

0.1 % 


You can also control the way in which zones are extended by using 
the LIB$M—VM—EXTEND—AREA attribute. This attribute specifies that 
when new pages are allocated for a zone, they should be appended to an 
existing area if the pages are adjacent to an existing area. 

• Block size 

The block size attribute specifies the number of bytes in the basic 
allocation quantum for the zone. 

All allocation requests are rounded up to a multiple of the block size. 
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The block size must be a power of 2 in the range 8 to 512. Table 8-2 lists 
the possible block sizes that may be used. 

Table 8-2 Possible Values for the Block Size Attribute 

Power of 2 Actual Block Size 


2 3 

8 

2 4 

16 

5 

32 

2 6 

64 

2 7 

128 

2 8 

256 

2 9 

512 


By adjusting the block size, you can control the effects of internal 
fragmentation and external fragmentation. Internal fragmentation occurs 
when the request size is rounded up and more bytes are allocated than are 
required to satisfy the request. External fragmentation occurs when there 
are many small blocks on the free list, but none of them is large enough 
to satisfy an allocation request. 

If you do not specify a value for block size, a default of eight bytes is 
used. 

• Alignment 

The alignment attribute specifies the required address boundary alignment 
for each block allocated. The alignment value must be a power of 2 in the 
range 4 to 512. 

The block size and alignment values are closely related. If you are 
not using boundary-tagged blocks, the larger value of block size and 
alignment controls both the block size and alignment. If you are using 
boundary-tagged blocks, you can minimize the overhead for the boundary 
tags by specifying a block size of 8 and an alignment of 4 (longword 
alignment). Note that the VAX interlocked queue instructions require 
quadword alignment, so you should not specify longword alignment for 
blocks that will be inserted on an interlocked queue. 

If you do not specify an alignment value, a default of 8 is used (alignment 
on a quadword boundary). 

• Page limit 

You can specify the maximum number of 512-byte pages that can be 
allocated to the zone. If you do not specify a page limit, the only limit 
is the total process virtual address limit imposed by VAX/VMS process 
quotas and system parameters. 

• Fill on allocate 

If you do not specify allocation fill, LIB$GET_VM does not initialize the 
contents of the blocks of memory that it supplies. The contents of the 
memory are unpredictable, and your program must assign a value to each 
location it uses. 
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In many applications, it is convenient to initialize every byte of 
dynamically allocated memory to the value 0. You can request that 
LIB$GET_VM do this initialization by specifying the allocation-fill 
attribute LIB$M_VM_GET_EILLO when you create the zone. 

If your program is not using allocation-fill, it may be very difficult to locate 
bugs where the program is not properly initializing dynamically allocated 
memory. As a debugging aid, you can request that LIB$GET_VM 
initialize every byte to FF (hexadecimal) by specifying the allocation-fill 
attribute LIB$M_VM_GET_FILL1 when you create the zone. 

• Fill on free 

In complex programs using heap storage, it can be very difficult to locate 
bugs where the program frees a block of memory but continues to make 
references to that block of memory. As a debugging aid, you can request 
that LIB$FREE_VM write bytes containing 0 or FF (hexadecimal) into 
each block of memory when it is freed; specify one of the attributes 
LIB$M_VM_FREE_FILLO or LIB$M_VM_FREE_FILL1. 


8.3.2 The Default Zone 

The Run-Time Library provides a default zone that is used if you do not 
specify a zone-id argument when you call LIB$GET_VM or LIB$FREE_VM. 
The default zone provides compatibility with earlier versions of LIB$GET__ 
VM and LIB$FREE_VM, which did not support multiple zones. 

Programs that do not place heavy demands on heap storage can simply use 
the default zone for all heap storage allocation. They do not need to call 
LIB$CREATE_VM_ZONE and LIB$DELETE_VM_ZONE, and they can omit 
the zone-id argument when calling LIB$GET_VM and LIB$FREE_VM. The 
zone-id for the default zone has the value zero. 

The default zone has the following attribute values: 


Table 8-3 Attribute Values for the Default Zone 


Attribute 

Value 

Algorithm 

First Fit 

Area extension size 

128 pages 

Block size 

8 bytes 

Alignment 

Quadword boundary 

Boundary tags 

No boundary tags 

Page limit 

No page limit 

Fill on allocate 

No fill on allocate 

Fill on free 

No fill on free 


8.3.3 Zone Identification 

A zone is a logically independent memory pool or subheap. You can create 
zones by calling LIB$CREATE_VM_ZONE or LIB$CREATE_USER_VM_ 
ZONE. These procedures return as an output argument a unique 32-bit zone 
identifier (zone-id) which is used in subsequent procedure calls where a zone 
identification is needed. 
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You can specify zone-id as an optional argument when you call LIB$GET_ 
VM to allocate a block of memory. If you do specify zone-id when you 
allocate memory, you must specify the same zone-id value when you call 
LIB$FREE_VM to free the memory. LIB$FREE_VM will return an error status 
if you do not provide the correct zone-id. 

Modular procedures that allocate and free heap storage must use zone 
identifications in a consistent fashion. There are several approaches you can 
use in designing a set of modular procedures to insure consistency in using 
zone identifications: 

• Each procedure that allocates or frees heap storage has a zone-id 
argument so the caller can specify the zone to be used. 

• The modular procedure package provides ALLOCATE and FREE 
procedures for each type of dynamically allocated object. These 
procedures keep track of zone identifications in an implicit argument, 

in static storage, or in the dynamically allocated objects. The caller need 
not be concerned with the details of zone identifications. 

• By convention, the set of modular procedures could do all allocate and 
free operations in the default zone. 

The zone-id for the default zone has the value 0 (see Section 8.3.2 for more 
information on the default zone). You can allocate and free blocks of memory 
in the default zone by specifying a zone-id of 0 or by omitting the zone-id 
argument when you call LIB$GET_VM and LIB$FREE_VM. You cannot use 
LIB$DELETE_VM_ZONE or LIB$RESET_VM_ZONE on the default zone; 
these procedures return an error status if the zone-id is 0. 


8.3.4 Creating a Zone 

LIB$ CREATE—VM_ZONE creates a new zone and sets zone attributes 
according to arguments that you supply. LIB$CREATE_VM—ZONE returns a 
zone-id value for the new zone that you use in subsequent calls to LIB$GET_ 
VM, LIB$FREE_VM and LIB$DELETE_VM—ZONE. 


8.3.5 Deleting a Zone 

LIB$DELETE_VM_ZONE deletes a zone and returns all pages owned by 
the zone to the processwide page pool managed by LIB$GET_VM_PAGE. 
Your program must not do any further operations on the zone after you call 
LIB$DELETE_VM—ZONE. 

It takes less execution time to free memory in a single operation by calling 
LIB$DELETE_VM—ZONE than to individually account for and free every 
block of memory that was allocated by calling LIB$GET—VM. Of course, you 
must be sure that your program is no longer using the zone or any of the 
memory in the zone before you call LIB$DELETE_VM_ZONE. 

If you have specified deallocation filling, LIB$DELETE_VM_ZONE will fill 
all of the allocated blocks that are freed. 
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8.3.6 Resetting a Zone 

LIB$RESET_VM_ZONE frees all the blocks of memory that were previously 
allocated from the zone. The memory becomes available to satisfy 
further allocation requests for the zone; the memory is not returned to 
the processwide page pool managed by LIB$GET_VM_PAGE. Your program 
can continue to use the zone after you call LIB$RESET_VM_ZONE. 

It takes less execution time to free memory in a single operation by calling 
LIB$RESET_VM_ZONE than to individually account for and free every block 
of memory that was allocated by calling LIB$GET_VM. Of course, you must 
be sure that your program is no longer using any of the memory in the zone 
before you call LIB$RESET_VM_ZONE. 

If you have specified deallocation filling, LIB$RESET__VM_ZONE will fill all 
of the allocated blocks that are freed. 

Since LIB$RESET_VM_ZONE does not return any pages to the processwide 
page pool, you should reset a zone only if you expect to reallocate almost 
all of the memory that is currently owned by the zone. If the next cycle 
of reallocation might use much less memory, it is better to delete the zone 
(LIB$DELETE_VM_ZONE) and then recreate it (LIB$CREATE_VM_ZONE). 


8.4 Allocating and Freeing Blocks 

The Run-Time Library heap management procedures LIB$GET_VM and 
LIB$FREE_VM provide the mechanism for allocating and freeing blocks of 
memory. 

LIB$GET_VM and LIB$FREE_VM are fully reentrant, so they can be called 
by code running at AST level or in an Ada multitasking environment. Several 
threads of execution may be simultaneously allocating or freeing memory in 
the same zone or in different zones. 

All memory allocated by LIB$GET_VM has user-mode read-write access, 
even if the call to LIB$GET_VM is made from a more privileged access mode. 

The rules for using LIB$GET_VM and LIB$FREE_VM are as follows: 

• Any memory you free by calling LIB$FREE_VM must have been allocated 
by a previous call to LIB$GET_VM. You cannot allocate memory by 
calling $EXPREG or $CRETVA and then free it using LIB$FREE_VM. 

• When you free a block of memory by calling LIB$FREE_VM, you must 
use the same zone-id value as when you called LIB$GET_VM to allocate 
the block. If the block was allocated from the default zone, you must 
either specify a zone-id of zero or omit the zone-id argument when you 
call LIB$FREE_VM. 

• You cannot free part of a block that was allocated by a call to LIB$GET_ 
VM; the whole block must be freed by a single call to LIB$FREE_VM. 

• You cannot combine contiguous blocks of memory that were allocated 
by several calls to LIB$GET_VM into one larger block that is freed by a 
single call to LIB$FREE_VM. 

• All memory allocated by LIB$GET_VM is aligned according to the 
alignment attribute for the zone; all memory freed by LIB$FREE_VM must 
have the correct alignment for the zone. An error status will be returned 
if you attempt to free a block that is not aligned properly. 
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8.5 Allocation Algorithms 

The Run-Time Library heap management procedures provide four algorithms 
that are used to allocate and free memory, and that are used to manage 
blocks of free memory. 


Table 8-4 Allocation Algorithms 


Code 

Symbol 

Description 

1 

LIB$K_VM_FIRST_FIT 

First Fit 

2 

LIB$K_VM_QUICK_FIT 

Quick Fit lookaside list 

3 

LIB$K_VM_FREQ_SIZES 

Frequent Sizes lookaside list 

4 

LIB$K_VM_FIXED 

Fixed Size Blocks 


The Quick Fit and Frequent Sizes algorithms use lookaside lists to speed up 
allocation and freeing for certain request sizes. A lookaside list is the software 
analog of a hardware cache. It takes less time to allocate or free a block on a 
lookaside list. 

For each of the algorithms, LIB$GET_VM performs one or more of the 
following operations: 

• Try to allocate a block from an appropriate lookaside list. 

• Scan the list of areas owned by the zone. For each area, try to allocate 
a block from the free list; then try to allocate a block from the block of 
unallocated memory at the end of the area. 

• Add a new area to the zone and allocate the block from that area. 

For each of the algorithms, LIB$FREE_VM performs one or more of the 
following operations: 

• Place the block on a lookaside list associated with the zone if there is an 
appropriate list. 

• Locate the area that contains the block. If the zone has boundary tags, the 
tags encode the area; otherwise, scan the list of areas owned by the zone 
to find the correct area. 

• Insert the block on the area free list and check for merges with adjacent 
free blocks. 

If the zone has boundary tags, check the tags of adjacent blocks; if no 
merge occurs, simply insert the block at the tail of the free list. 

If the zone does not have boundary tags, scan the sorted free list to find 
the correct insertion point. Check the preceding and following blocks for 
merges. 


8-14 












Memory Allocation Procedures 

Allocation Algorithms 


8.5.1 First Fit 


The First Fit algorithm (LIB$K_VM_FIRST_FIT) maintains a linked list of free 
blocks. If the zone does not have boundary tags, the free list is kept sorted 
in order of increasing memory address. An allocation request is satisfied by 
the first block on the free list that is large enough; if the first free block is 
larger than the request size, it is split and the fragment is kept on the free list. 
When a block is freed, it is inserted in the free list at the appropriate point; 
adjacent free blocks are merged to form larger free blocks. 


8.5.2 Quick Fit 


The Quick Fit algorithm (LIB$K_VM_QUICK_FIT) maintains a set of 
lookaside lists indexed by request size for request sizes in a specified range. 
For request sizes that are not in the specified range, a First Fit list of free 
blocks is maintained. An allocation request is satisfied by removing a block 
from the appropriate lookaside list; if the lookaside list is empty, a First Fit 
allocation is done. When a block is freed, it is placed on a lookaside list or 
the First Fit list according to its size. 

Free blocks that are placed on a lookaside list are not merged with adjacent 
free blocks, nor are they split to satisfy a request for a smaller block. 


8.5.3 Frequent Sizes 

The Frequent Sizes algorithm (LIB$K_VM_FREQ_SIZES) is similar to Quick 
Fit in that it maintains a set of lookaside lists for some block sizes. You 
specify the number of lookaside lists when you create the zone; the sizes 
associated with those lists are determined by the actual sizes of blocks that 
are freed. An allocation request is satisfied by searching the lookaside lists for 
a matching size; if no match is found, a First Fit allocation is done. When a 
block is freed, the block is placed on a lookaside list with matching size, on 
an empty lookaside list, or on the First Fit list if no lookaside list is available. 
Similarly to Quick Fit, free blocks on lookaside lists are not merged or split. 


8.5.4 Fixed Size 


The Fixed Size algorithm (LIB$K_VM_FIXED) maintains a single queue of 
free blocks. There is no First Fit free list, and no splitting or merging of 
blocks occurs. 
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8.6 User-Defined Zones 

When you create a zone by calling LIB$CREATE_VM_ZONE, you must 
select an allocation algorithm from the fixed set provided by the Run¬ 
Time Library. You can tailor the characteristics of the zone by specifying 
various zone attributes. User-defined zones provide additional flexibility and 
control by letting you supply procedures for the allocation and deallocation 
algorithms. 

You create a user-defined zone by calling LIB$CREATE—USER—VM—ZONE. 
Instead of supplying values for a fixed set of zone attributes, you provide 
procedures that perform the following operations for the zone: 

• Allocate a block of memory 

• Free a block of memory 

• Reset the zone 

• Delete the zone 

Each time that one of the Run-Time Library heap management procedures 
(LIB$GET_VM, LIB$FREE_VM, LIB$RESET_VM—ZONE, LIB$DELETE— 
VM—ZONE) is called to perform an operation on a user-defined zone, the 
corresponding procedure that you specified is called to perform the actual 
operation. It is not necessary to make any changes in the calling program in 
order to use user-defined zones; their use is transparent. 

You do not have to provide procedures for all four of the operations listed 
above if you know that your program will not perform certain operations. If 
you omit some of the operations and your program attempts to use them, an 
error status will be returned. 

Applications of user-defined zones include the following: 

• You can provide your own specialized allocation algorithms. These 
algorithms can in turn invoke LIB$GET_VM, LIB$GET—VM—PAGE, 
$EXPREG, or other VAX/VMS system services. 

• You can use a user-defined zone to monitor memory allocation operations. 
Example 8-1 shows some simple monitoring programs that print a record 
of each call to allocate or free memory in a zone. 
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Example 8-1 Monitoring Heap Operations with a User-defined 
Zone 


c+ 

C This is the main program that creates a zone and exercises it. 

C 

C Note that the main program simply calls LIB$GET_VM and LIB$FREE_VM. 

C It contains no special coding for user-defined zones. 

C- 

PROGRAM MAIN 
IMPLICIT INTEGER(A-Z) 

CALL MAKE_ZONE(ZONE) 

CALL LIB$GET.VM(10, II, ZONE) 

CALL LIB$GET_VM(20, 12. ZONE) 

CALL LIB$FREE_VM(10, II. ZONE) 

CALL LIB$RESET_VM.ZONE(ZONE) 

CALL LIB$DELETE_VM.ZONE(ZONE) 

END 

C+ 

C This is the subroutine that creates a user-defined zone for monitoring. 
C Each GET, FREE, or RESET prints a line of output on the terminal. 

C Errors are signaled. 

C- 

SUBROUTINE MAKE.ZONE(ZONE) 

IMPLICIT INTEGER (A-Z) 

EXTERNAL GET.RTN, FREE.RTN, RESET.RTN, LIB$DELETE.VM_ZONE 
C+ 

C Create the primary zone. The primary zone supports 
C the actual allocation and freeing of memory. 

C- 


STATUS = LIB$CREATE_VM.ZONE(REAL_ZONE) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 


C+ 

C Create a user-defined zone that monitors operations on REAL_Z0NE. 
C- 

STATUS = LIB$CREATE_USER_VM_ZONE(USER_ZONE, REAL_Z0NE, 

1 GET.RTN, 

1 FREE.RTN, 

1 RESET.RTN, 

1 LIB$DELETE_VM_ZONE) 

IF (.NOT. STATUS) CALL LIB$SIGNAL(%VAL(STATUS)) 

C+ 

C Return the zone-id of the user-defined zone to the caller to use. 
C- 


ZONE = USER.ZONE 
END 


(Continued on next page) 
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Example 8-1 (Cont.) Monitoring Heap Operations with a User- 

defined Zone 


c+ 

C GET routine tor user-defined zone. 

C- 

FUNCTION GET_RTN(SIZE, ADDR, ZONE) 

IMPLICIT INTEGER(A-Z) 

STATUS = LIB$GET_VM(SIZE, ADDR, ZONE) 

IF (.NOT. STATUS) THEN 

CALL LIB$SIGNAL(y,VAL(STATUS)) 

ELSE 

TYPE 10. SIZE, ADDR 

10 FORMAT(' Allocated '.14,' bytes at ',Z8) 

END IF 

GET.RTN = STATUS 
END 

C+ 

C FREE routine lor user-defined zone. 

C- 

FUNCTION FREE_RTN(SIZE, ADDR, ZONE) 

IMPLICIT INTEGER(A-Z) 

STATUS = LIB$FREE_VM(SIZE, ADDR. ZONE) 

IF (.NOT. STATUS) THEN 

CALL LIB$SIGNAL(y,VAL(STATUS)) 

ELSE 

TYPE 20, SIZE, ADDR 

20 FORMAT(' Freed ',14,' bytes at ' ,Z8) 

END IF 

FREE.RTN = STATUS 
END 

C+ 

C RESET routine for user-defined zone. 

C- 

FUNCTION RESET.RTN(ZONE) 

IMPLICIT INTEGER(A-Z) 

STATUS = LIB$RESET_VM_ZONE(ZONE) 

IF (.NOT. STATUS) THEN 

CALL LIB$SIGNAL (y.VAL (STATUS) ) 

ELSE 

TYPE 30, ZONE 

30 FORMAT(' Reset zone at Z8) 

END IF 

RESET.RTN = STATUS 
END 


8.7 Interactions with Other Run-Time Library Procedures 

Section 8.1 describes a 3-level hierarchy of memory allocation procedures 
consisting of the following: 

1 VAX/VMS memory management system services 

2 Run-Time Library page management procedures LIB$GET_VM_PAGE 
and LIB$FREE_VM_JPAGE 

3 Run-Time Library heap management procedures LIB$GET_VM and 
LIB$FREE_VM 
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The Run-Time Library and various VAX programming languages provide 
another level of more specialized allocation procedures. 

• The Run-Time Library dynamic string package provides a set of 
procedures for allocating and freeing dynamic strings. The set of 
procedures includes the following: 

LIB$SGET1_DD, LIB$SFREE1_DD 
LIB$SFREEN_DD 
STR$GET1_DX, STR$FREE1_DX 

• VAX Ada provides allocators and the UNCHECKED-DEALLOCATION 
package for allocating and freeing memory. 

• VAX PASCAL provides the NEW and DISPOSE procedures for allocating 
and freeing memory. 

• VAX PL/I provides ALLOCATE and FREE statements for allocating and 
freeing memory. 

A program containing procedures written in several VAX languages may 
use a number of these facilities at the same time. This does not cause any 
problems or impose any restrictions on the user since all of these are layered 
on the Run-Time Library heap management procedures. 

Note: To ensure correct operation, memory that is allocated by one of the 
higher-level allocators listed above can only be freed by using the 
corresponding deallocation procedure. That is, memory allocated by 
PASCAL NEW must be freed by calling PASCAL DISPOSE, and a 
dynamic string can be freed only by calling one of the string package 
deallocation procedures. 


8.8 Interactions with VAX/VMS System Services 

The Run-Time Library page management and heap management procedures 
are implemented as layers built on the VAX/VMS memory management 
system services. In general, modular procedures should use the Run-Time 
Library procedures rather than directly call VAX/VMS memory management 
system services. However, there are some situations where you must use 
both. This section describes relationships between the Run-Time Library and 
VAX/VMS memory management. See the VAX/VMS System Services Reference 
Manual for descriptions of the memory management system services. 

You can use the Expand Region system service ($EXPREG) to create pages of 
virtual memory in the program region (PO space) for your process. VAX/VMS 
keeps track of the first free page address at the end of PO space, and it 
updates this free page address whenever you call $EXPREG or $CRETVA. 
The LIB$GET_VM_PAGE procedure calls $EXPREG to create pages, so there 
will be no conflicting address assignments when you call $EXPREG directly. 

You should avoid using the Create Virtual Address Space system service 
($CRETVA), because you must specify the range of virtual addresses when it 
is called. If the address range you specify contains pages that already exist, 
$CRETVA deletes those pages and re-creates them as demand-zero pages. 

It may be difficult to avoid conflicting address assignments if you are using 
Run-Time Library procedures and $CRETVA. 

You must not use the Contract Region system service ($CNTREG) because 
other procedures or the VAX Record Management Services (RMS) may have 
allocated pages at the end of the program region. 
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You can change the protection on pages your program has allocated by 
calling the Set Protection system service (SSETPRT). All pages allocated 
by LIBS GET_VM_P AGE have user-mode read-write access. If you change 
protection on pages allocated by LIB$GET_VM__PAGE, you must reset the 
protection to user-mode read-write before calling LIB$FREE_VM__PAGE to 
free the pages. 

You can use the Create and Map Section system service ($CRMPSC) to map a 
file into your virtual address space. In order to map a file, you must provide 
a range of virtual addresses for the file. One way to do this is to specify the 
Expand Region option (SEC$M_EXPREG) when you call $CRMPSC. This 
method assigns addresses at the end of PO space, similar to the $EXPREG 
system service. Alternatively, you can provide a specific range of virtual 
addresses when you call SCRMPSC; this is similar to allocating pages by 
calling SCRETVA. If you assign a specific range of addresses, you must avoid 
conflicts with other procedures. One way to do this is to allocate memory by 
calling LIB$GET__VML_PAGE, and then use that memory to map the file. The 
complete sequence of steps is as follows: 

1 Call LIB$GET_VM_PAGE to allocate a contiguous group of (n+1) pages. 

The first n pages will be used to map the file; the last page serves as a 
guard page. 

2 Call SCRMPSC using the first n pages to map the file into your process 
address space. 

3 Process the file. 

4 Call $DELTVA to delete the first n pages and unmap the file. 

5 Call $CRETVA to recreate the n pages of virtual address space as 
demand-zero pages. 

6 Call LIB$FREE_VM_PAGE to free (n+1) pages of memory and return it to 
the processwide page pool. 

The method described above is satisfactory for mapping small files of a few 
hundred pages, but it has severe limitations in mapping very large files. As 
discussed in Section 8.2, you should not use LIB$GET_VM_PAGE to allocate 
very large groups of contiguous pages (over 1000 contiguous pages in a single 
request). Also, when you allocate memory by calling LIB$GET_VM_PAGE 
(and thus $EXPREG), the pages are charged against your process page file 
quota. Your page file quota is not charged if you call SCRMPSC with the 
SEC$M_EXPREG option. 

You can process very large files using SCRMPSC by first providing a pool 
of pages that is sufficient for your program and then using SCRMPSC and 
SDELTVA to map and unmap the file. Use LIB$SHOW__VM to obtain an 
estimate of how much dynamically allocated memory your program requires; 
round this number up and allow for increased memory usage in the future. 
You can then use the memory estimate as follows: 

1 At the beginning of your program, include code to call LIB$GET__VM_ 
PAGE and allocate the estimated number of pages. You should not 
request a large number of pages in one call to LIBSGET__VM_PAGE, 
because this would require contiguous allocation of the pages. 

2 Call LIB$FREE_VM__PAGE to free all the pages allocated in STEP 1; this 
establishes a pool of free pages for your program. 

3 Open files that your program needs; note that RMS may allocate buffers 
in PO space. 
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4 Call $CRMPSC specifying SEC$M__EXPREG to map the file into your 
process address space at the end of PO space. 

5 Process the file. 

6 Call $DELTVA specifying the address range to release the file. If no 
additional pages were created after you mapped the file, $DELTVA will 
contract your address space. Your program can repeat the process of 
mapping a file without continually expanding its address space. 
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Access to VAX/VMS System Components 


One of the functions of the Run-Time Library is to provide a callable interface 
to components of VAX/VMS that are difficult to use in a high-level language. 
Run-Time Library procedures allow access to the following: 

• System services 

• The Command Language Interpreter 

• Some VAX machine instructions 

In addition, Run-Time Library procedures allow you to perform other 
operations that involve interaction with the operating system. For example, 
you can perform the following operations: 

• Allocate the resources that your process needs, such as virtual memory 
and event flags 

• Generate and display timing statistics while your program is running 

• Obtain and modify some of the default characteristics of the line printer 
output 

• Obtain the system date and time in various formats 

• Set up and use binary trees 

• Search for specified files 

• Get and put strings in the process common storage area 


9.1 System Service Access Procedures 

You can usually call VAX/VMS system services directly from your program. 
However, system services return only fixed-length strings. In some 
applications, you may want the result of a system service to be returned as 
a character array, dynamic string, or variable-length string. For this reason, 
the Run-Time Library provides jacket procedures for the system services that 
return strings. 

You call these procedures exactly as you would the corresponding system 
service, but you can pass an output argument of any valid string class. The 
procedures write the output string using the semantics (fixed, varying, or 
dynamic) associated with the string's descriptor. 

The jacket procedures follow the conventions established for all Run-Time 
Library procedures, except that the arguments are listed in the order of the 
arguments for the corresponding system service. Thus, they may not be listed 
in the standard Run-Time Library order (read, modify, write). 

For example, LIB$SYS_ASCTIM calls the system service $ASCTIM to convert 
a binary date and time value to ASCII text. It returns the resulting string 
using the semantics that the calling program specifies in the destination string 
argument. 
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For further information on the operations of the system services, see the 
VAX/VMS System Services Reference Manual. 

The Run-Time Library procedures provide access only to the system services 
that produce output strings, listed in Table 9-1. The corresponding Run-Time 
Library procedures recognize all VAX string classes. 

The Run-Time Library does not provide jacket routines for all the system 
services that accept strings as input. Your program should pass only 
fixed-length or dynamic input strings to all system services and Run-Time 
Library jacket routines. 


Table 9-1 System Service Access Procedures 


Entry Point 

System Service 

Function 

LIB$SYS_ASCTIM 

$ASCTIM 

Converts system time in binary form 
to ASCII text 

LIB$SYS_FAO 

$FAO 

Converts a binary value to ASCII text 

LIB$SYS_FAOL 

$FAOL 

Converts a binary value to ASCII text, 
using a list argument 

LIB$SYS_GETMSG 

SGETMSG 

Obtains a system or user-defined 
message text 

LIB$SYS_TRNLOG 

$TRNLOG 

Returns the translation of the 
specified logical name 


9.2 Access to the Command Language Interpreter 

Two Command Language Interpreters (CLIs) are available under VAX/VMS: 
DCL and MCR. The Run-Time Library provides several procedures that 
provide access to the VAX/VMS CLI callback facility. These procedures allow 
your program to call the current CLI. In most cases, these procedures are 
called from programs that execute as part of a command procedure. They 
allow the command procedure and the CLI to exchange information. 

These procedures call the CLI associated with the current process to perform 
the specified function. In some cases, however, there is no CLI present. 

For example, the program may be running directly as a subprocess or a 
detached process. If there is no CLI present, these procedures return the 
status LIB$_NOCLI. Therefore, you should be sure that these procedures will 
only be called when a CLI is active. Table 9-2 lists the Run-Time Library 
procedures that access the Command Language Intepreter. 

The following procedures execute only when the current Command Language 
Interpreter is DCL: 

LIB$GET_SYMBOL 

LIB$SET_SYMBOL 

LIB$DELETE_SYMBOL 

LIB$DISABLE_CTRL 
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LIB$ENABLE_CTRL 
LIB$SPAWN 
LIB$ ATTACH 


Table 9-2 CLI Access Procedures 
Entry Point Function 


Access to Foreign Commands 
LIB$GET_FOREIGN Gets a command line 


Exit Program and Activate CLI 

LIB$DO_COMMAND Executes a command line after exiting program 

LIB$RUN_PROGRAM Runs another program after exiting current program 

(chain) 


CLI Symbols 

LIB$GET_SYMBOL Returns value of a CLI symbol as a string 

LIB$DELETE_SYMBOL Deletes a CLI symbol 
LIB$SET_SYMBOL Defines or redefines a CLI symbol 


CLI Process Logical Names 

LIB$DELETE_LOGICAL Deletes a supervisor-mode process logical name 

LIB$SET_LOGICAL Defines or redefines a supervisor-mode process 

logical name 

Disable and Enable Control Characters 

LIB$DISABLE_CTRL Disables CLI interception of control characters 

LIB$ENABLE_CTRL Enables CLI interception of control characters 


Connect to a Subprocess 

LIBS ATTACH Attaches a terminal to another process 

LIBSSPAWN Creates a subprocess of the current process 


9.2.1 Obtaining the Command Line 

LIB$GET_JFOREIGN returns the contents of the command line that you 
use to activate an image. It can be used to give your program access to the 
qualifiers of a foreign command or to prompt for further command line text. 

A foreign command is a command that you can define and then use as if it 
were a DCL or MCR command in order to run a program. When you use 
the foreign command at command level, the Command Language Interpreter 
parses the foreign command only and activates the image. It ignores any 
options or qualifiers that you have defined for the foreign command. Once 
the CLI has activated the image, the program can call LIB$GET__FOREIGN 
to obtain and parse the remainder of the command line (after the command 
itself) for whatever options it may contain. 

The VAX/VMS DCL Dictionary shows how to define a foreign command. 
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The action of LIB$GET_FOREIGN depends on the environment in which the 
image is activated: 

• If you use a foreign command to invoke the image, you can call 
LIB$GET_FOREIGN to obtain the command qualifiers following the 
foreign command. You can also use LIB$GET_FOREIGN to prompt 
repeatedly for more qualifiers after the command. This technique is 
illustrated in the example. 

• If the image is in the SYS$SYSTEM: directory, the image can be invoked 
by the DCL MCR command or by the MCR Command Language 
Interpreter. In this case, LIB$GET_FOREIGN returns the command line 
text following the image name. 

• If the image is invoked by a DCL RUN command, LIB$GET_FOREIGN 
can be used to prompt for additional text. 

• If the image is not invoked by a foreign command or MCR, or if there is 
no information remaining on the command line, and the user-supplied 
prompt is present, LIB$GET_INPUT is called to prompt for a command 
line. If the prompt is not present, LIB$GET_FOREIGN returns a zero 
length string. 

Example 

The following PL/I example illustrates the use of the optional force-prompt 
argument to permit repeated calls to LIB$GET_FOREIGN. The command 
line text will be retrieved on the first pass only; after this, the program will 
prompt from SYS$INPUT. 

EXAMPLE: PROCEDURE OPTIONS (MAIN); 

^INCLUDE $STSDEF; /* Status-testing definitions */ 

DECLARE COMMAND.LINE CHARACTER(80) VARYING. 

PROMPT.FLAG FIXED BINARY(31) INIT(O). 

LIB$GET_FOREIGN ENTRY (CHARACTERS) VARYING. 

CHARACTERS) VARYING. 

FIXED BINARY(15), 

FIXED BINARY(31)) 

OPTIONS(VARIABLE) RETURNS (FIXED BINARY(31)), 

RMS$_E0F GLOBALREF FIXED BINARY(31) VALUE; 

/* Call LIB$GET_FOREIGN repeatedly to obtain and print 
subcommand text. Exit when end-of-file is found. */ 

DO WHILE Cl'B); /* Do while TRUE */ 

STSIVALUE = LIBIGET.FOREIGN 

(COMMAND.LINE,'Input: '., 

PROMPT.FLAG); 

IF STS$SUCCESS THEN 

PUT LIST (' Command was ',COMMAND.LINE); 

ELSE DO; 

IF STS$VALUE ~= RMS$.EOF THEN 
PUT LIST ('Error encountered'); 

RETURN; 

END; 

PUT SKIP; /* Skip to next line */ 

END; /* End of DO WHILE loop */ 

END; 


Assuming that this program is present as SYS$SYSTEM:EXAMPLE.EXE, you 
can define the foreign command EXAMPLE to invoke it. 

$ EXAM*PLE :== $EXAMPLE 
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Note the optional use of the asterisk in the symbol name to denote an 
abbreviated command name. This permits the command name to be 
abbreviated as EXAM, EX AMP, EXAMPL or fully specified as EXAMPLE. 

See the VAX/VMS DCL Dictionary for information on abbreviated command 
names. 

Note also the use of the dollar sign before the image name. This is necessary 
in foreign commands. 

Now assume that a user runs the image by typing the foreign command and 
giving "subcommands" which the program displays. Text typed by the user is 
in red. 

$ EXAMP subcommand 1 

Command was SUBCOMMAND 1 

Input: Subcommand 2 

Command was SUBCOMMAND 2 

Input: ~Z 

$ 

The first "subcommand" was obtained from the command line; the second 
was prompted for. The program terminated when the user pressed CTRL/Z 
(echoed as ~Z) to indicate end-of-file. 


9.2.2 Chaining from One Program to Another 

LIB$RUN_PROGRAM causes the current image to exit at the point of the 
call and directs the Command Language Interpreter, if one is present, to start 
running another program. If LIB$RUN_PROGRAM executes successfully, 
control passes to the second program; if not, control passes to the Command 
Language Interpreter. The calling program cannot regain control. This 
technique is called chaining. 

This procedure is provided primarily for compatibility with PDP-11 systems, 
where chaining is used to extend the address space of a system. It may also 
be useful in a VAX/VMS environment where address space is severely limited 
and large images are not possible. For example, you might use chaining to 
perform system generation (SYSGEN) on a small virtual address space, 
because of a lack of disk space. 

With LIB$RUN_PROGRAM, the calling program can pass arguments to the 
next program in the chain only by using the common storage area. One 
way to do this is for the calling program to call LIB$PUT_COMMON to 
pass the information into the common area. Then the called program calls 
LIB$GET_COMMON to retrieve the data. 

In general, this practice is not recommended. There is no convenient way 
to specify the order and type of arguments passed into the common area, so 
programs that pass arguments in this way must know about the format of the 
data before it is passed. FORTRAN COMMON or BASIC MAP/COMMON 
areas are global OWN storage. When you use this type of storage, it is 
very difficult to keep your program modular and AST-reentrant. Further, 
LIB$RUN_PROGRAM cannot be used if no Command Language Interpreter 
is present, as in the case of image subprocesses and detached subprocesses. 
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Examples 

The following PL/I example illustrates the use of LIB$RUN_PROGRAM. It 
prompts the user for the name of a program to run and calls the Run-Time 
Library procedure to execute the specified program. 

CHAIN: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 

DECLARE LIB$RUN_PROGRAM ENTRY (CHARACTER (*)) /* Address of string 

/* descriptor */ 

RETURNS (FIXED BINARY (31)); /* Return status */ 

'/.INCLUDE ISTSDEF; /* Include definition of return status values */ 

DECLARE COMMAND CHARACTER (80); 

GET LIST (COMMAND) OPTIONS (PROMPT('Program to run: ')); 

STSlVALUE = LIB$RUN_PROGRAM (COMMAND); 

/* 

If the function call is successful, the program will terminate 
here. Otherwise, return the error status to command level. 

*/ 

RETURN (STSIVALUE); 

END CHAIN; 

This COBOL program also demonstrates LIB$RUN_PROGRAM. When you 
compile and link these two programs, the first calls LIB$RUN_PROGRAM, 
which activates the executable image of the second. This call results in the 
following screen display: 

THIS MESSAGE DISPLAYED BY PROGRAM PR0G2 
WHICH WAS RUN BY PROGRAM PR0G1 
USING LIBIRUN.PROGRAM 

IDENTIFICATION DIVISION. 

PROGRAM-ID. PR0G1. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 PROG-NAME PIC X(9) VALUE "PR0G2.EXE". 

01 STAT PIC 9(9) COMP. 

88 SUCCESSFUL VALUE 1. 

PROCEDURE DIVISION. 

001-MAIN. 

CALL "LIBIRUN.PROGRAM” 

USING BY DESCRIPTOR PROG-NAME 
GIVING STAT. 

IF NOT SUCCESSFUL 

DISPLAY "ATTEMPT TO CHAIN UNSUCCESSFUL" 

STOP RUN. 

IDENTIFICATION DIVISION. 

PROGRAM-ID. PR0G2. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 

PROCEDURE DIVISION. 

001-MAIN. 

DISPLAY " ". 

DISPLAY "THIS MESSAGE DISPLAYED BY PROGRAM PR0G2". 

DISPLAY " ". 

DISPLAY "WHICH WAS RUN BY PROGRAM PR0G1". 

DISPLAY " ". 

DISPLAY "USING LIBIRUN.PROGRAM". 

STOP RUN. 
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9.2.3 Executing a CLI Command 

LIB$DO_COMMAND stops program execution and directs the Command 
Language Interpreter to execute a command. The procedure's argument is the 
text of the command line that you wish to be executed. 

This procedure is especially useful when you wish to execute a CLI command 
after your program has finished executing. For example, you could set up a 
series of conditions, each associated with a different command. You could 
also use the procedure to execute a SUBMIT or PRINT command to handle a 
file that your program has created. 

Because of the following restrictions on LIB$DO_COMMAND, you should be 
careful when you incorporate it in your program. 

• After the call to LIB$DO_COMMAND, the current image exits, and 
control cannot return to it. 

• The text of the command is passed to the current Command Language 
Interpreter. Because you can define your own CLI in addition to DCL 
and MCR, you must make sure that the command will be handled by the 
intended CLI. 

• If the procedure is called from a subprocess, it will not execute correctly, if 
no CLI is associated with a subprocess. 

You can also use LIB$DO_COMMAND to execute a DCL command file. To 
do this, include the at sign (@) along with a command file specification as the 
input argument to the procedure. 

There are also DCL CLI$ procedures that perform the functions of LIB$DO_ 
COMMAND. See the VAX/VMS DCL Dictionary for more information. 

Example 

The following PL/I example prompts the user for a DCL command to execute 
after the program exits: 


EXECUTE: PROCEDURE OPTIONS (MAIN) RETURNS (FIXED BINARY (31)); 

DECLARE LIB$DO_COMMAND ENTRY (CHARACTER (*)) /* Pass DCL command */ 

/* by descriptor */ 

RETURNS (FIXED BINARY (31)); /* Return status */ 

^INCLUDE ISTSDEF; /* Include definition of return status values */ 

DECLARE COMMAND CHARACTER (80); 

GET LIST (COMMAND) OPTIONS (PROMPTCDCL command to execute: ')); 

STS$VALUE = LIB$D0_C0MMAND (COMMAND); 

/* 

If the call to LIB$D0_C0MMAND is successful, the program will terminate 
here. Otherwise, it will return the error status to command level. 

*/ 

RETURN (STS$VALUE); 

END EXECUTE; 

This example displays the following prompt: 

DCL command to execute: 

What you type after this prompt determines the action of LIB$DO_ 
COMMAND. LIB$DO_COMMAND will execute any command that is 
entered as a valid string according to the syntax of PL/I. If the command you 
enter is incomplete, you will be prompted for the rest of the command. For 
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example, if you enter the SHOW command, you will receive the following 
prompt: 

$_Show what?: 


9.2.4 


Using Symbols and Logical Names 

The Run-Time Library provides seven procedures that give you access to the 
CLI callback facility. These routines allow a program to "call back" to the 
Command Language Interpreter to perform functions normally performed by 
CLI commands. These procedures perform the following functions: 


LIB$GET_SYMBOL 


LIB$SET_SYMBOL 


LIB$DELETE_SYMBOL 


LIB$SET_LOGICAL 


LIB$DELETE_LOGICAL 


Returns the value of a CLI symbol as a string. 

Optionally, this procedure also returns the length of 
the returned value and a value indicating whether the 
symbol was found in the local or global symbol table. 
This procedure executes only when the current CLI is 
DCL. 

Causes the CLI to define or redefine a CLI symbol. 

The optional argument specifies whether the symbol 
is to be defined in the local or global symbol table; the 
default is local. This procedure executes only when 
the current CLI is DCL. 

Causes the CLI to delete a symbol. 

An optional argument specifies the local or global 
symbol table. If this argument is omitted, the symbol 
is deleted from the local symbol table. This procedure 
executes only when the current CLI is DCL. 

Defines or redefines a supervisor-mode process 
logical name. 

Supervisor-mode logical names are not deleted when 
an image exits. This procedure is equivalent to the 
DCL DEFINE command. LIB$SET_LOGICAL allows the 
calling program to define a supervisor-mode process 
logical name without itself executing in supervisor 
mode. 

Deletes a supervisor-mode process logical name. 

This procedure is equivalent to the DCL DEASSIGN 
command. LIB$DELETE_LOGICAL does not require 
the calling program to be executing in supervisor 
mode to delete a supervisor-mode logical name. 


9.2.5 Disabling and Enabling Control Characters 

Two Run-Time Library procedures, LIB$ENABLE_CTRL and LIB$DISABLE_ 
CTRL, allow you to call the Command Language Interpreter in order to 
enable or disable control characters. These procedures take a longword bit- 
mask argument that specifies the control character or characters to be disabled 
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or enabled. Acceptable values for this argument are LIB$M_CLI_CTRLY and 
LIB$M_CLL_CTRLT. 

LIB$DISABLE_CTRL Disables CLI interception of control characters. 

This procedure performs the same function as the DCL 
command 

SET NOCONTROL = n, where n is equal to T or Y. 

It prevents the currently active CLI from intercepting the 
control character specified during an interactive session. 

For example, you might use LIB$DISABLE_CTRL to 
disable CLI interception of CTRL/Y. Normally, CTRL/Y 
interrupts the current command, command procedure, or 
image. If LIB$DISABLE_CTRL is called with LIB$M_CLI_ 
CTRLY specified as the control character to be disabled, 
CTRL/Y is treated like CTRL/U followed by a carriage 
return. 

LIB$ENABLE_CTRL Enables CLI interception of control characters. 

This procedure performs the same function as the DCL 
command 

SET CONTROL= n, where n is equal to T or Y. 

LIB$ENABLE_CTRL restores the normal operation of 
CTRL/Y or CTRL/T. 


9.2.6 Creating and Connecting to a Subprocess 

You can use LIB$SPAWN and LIB$ATTACH together to spawn a subprocess 
and attach the terminal to that subprocess. These procedures will execute 
correctly only if the current CLI is DCL. For more information on the SPAWN 
and ATTACH commands, see the VAX/VMS DCL Dictionary. 

LIBSSPAWN Spawns a subprocess. 

This procedure is equivalent to the DCL SPAWN command. 

It requests the CLI to spawn a subprocess for executing CLI 
commands. 

LIBS ATTACH Attaches the terminal to another process. 

This procedure is equivalent to the DCL ATTACH command. It 
requests the CLI to detach the terminal from the current process 
and reattach it to a different process. 


9.3 Access to VAX Machine Instructions 

The VAX instruction set was designed for efficient use by high-level 
languages, and therefore contains many functions which are directly useful in 
your programs. However, many of these functions cannot be used directly by 
high-level languages. 

The Run-Time Library provides procedures that allow your high-level 
language program to use most of VAX machine instructions that are 
otherwise unavailable. In most cases, these procedures simply execute the 
instruction, using the arguments you provide. Some procedures that accept 
string arguments, however, provide some additional functions that make 
them easier to use. 
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These procedures fall into the following categories: 

• Variable-length bit field instruction procedures (Section 9.3.1) 

• Integer and floating-point instructions (Section 9.3.2) 

• Queue instructions (Section 9.3.3) 

• Character string instructions (Section 9.3.4) 

• Procedure call instructions (Section 9.3.5) 

• Cyclic redundancy check instruction (Section 9.3.5) 

The VAX-11 Architecture Reference Manual describes the VAX instruction set 
in detail. 


Variable-Length Bit Field Instruction Procedures 

The variable-length bit field is a VAX data type used to store small integers 
packed together in a larger data structure. It is often used to store single flag 
bits. 

The Run-Time Library contains five procedures for performing operations on 
variable-length bit fields. These procedures give higher-level languages that 
do not have the inherent ability to manipulate bit fields direct access to the 
bit field instructions in the VAX instruction set. Furthermore, if a program 
calls a procedure written in a different language to perform some function 
that also involves bit manipulation, the called procedure can include a call to 
the Run-Time Library to perform the bit manipulation. 

Table 9-3 lists the Run-Time Library variable bit field procedures. 


Table 9-3 Variable Bit Field Procedures 


Entry Point 

Function 

LIB$EXTV 

Extracts a field from the specified variable bit field and returns it 
in sign-extended longword form. 

LIBSEXTZV 

Extracts a field from the specified variable bit field and returns it 
in zero-extended longword form. 

LIBSFFC 

Searches the specified field for the first clear bit. If it finds one, 
it returns SS$_NORMAL and the bit position (find-pos) of the 
clear bit. If not, it returns a failure status and sets the find-pos 
argument to the start position plus the size. 

LIB$FFS 

Searches the specified field for the first set bit. If it finds one, 
it returns SS$_NORMAL and the bit position (find-pos) of the 
set bit. If not, it returns a failure status and sets the find-pos 
argument to the start position plus the size. 

LIBSINSV 

Replaces the specified field with bits zero through [size- 1] of 
the source argument (src). If the size argument is zero, nothing 
is inserted. 


Three scalar attributes define a variable bit field: 

• Base address —the address of the byte in memory that serves as a reference 
point for locating the bit field. 

• Bit position —the signed longword containing the displacement of the least 
significant bit of the field with respect to the bit zero of the base address. 
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• Size —a byte integer indicating the size of the bit field in bits (in the range 
0 <= size <= 32). That is, a bit field can be no more than one longword 
in length. 

Figure 9-1 shows the format of a variable-length bit field. The shaded area 
indicates the field. 

Figure 9-1 Variable-Length Bit Field 
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Bit fields are zero-origin, which means that the procedure regards the first 
bit in the field as being the zero position. For more detailed information on 
VAX bit numbering and data formats, see the VAX-11 Architecture Reference 
Manual. 

The attributes of the bit field are passed to a Run-Time Library procedure in 
the form of three arguments in the order that they are listed below. 

Arguments 

pos 

VMS Usage: longword_signed 
type: longword integer (signed) 
access: read only 
mechanism: by reference 

Bit position relative to the base address. The pos argument is the address of a 
signed longword integer that contains this bit position. 

size 

VMs Usage: byte_unsigned 
type: byte (unsigned) 
access: read only 
mechanism: by reference 

Size of the bit field. The size argument is the address of an unsigned byte 
which contains this size. 

base 

VMs Usage: longword_unsigned 
type: longword (unsigned) 
access: read only 
mechanism: by reference 

Base address. The base argument contains the address of the base address. 
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Example 

The following BASIC example illustrates three Run-Time Library procedures. 
It opens the terminal as a file and specifies "HEX> " as the prompt. This 
allows you to get input from the terminal without the question mark that 
VAX BASIC normally adds to the prompt in an INPUT statement. The 
program calls OTS$CVT_TZ_L to convert the character string input to a 
longword. It then calls LIB$EXTZV once for each position in the longword to 
extract the bit in that position. Because LIB$EXTVZ is called with a function 
reference within the PRINT statement, the bits are displayed. 

10 EXTERNAL LONG FUNCTION 

OTS$CVT_TZ_L, ! Convert hex text to LONG 

LIB$EXTZV ! Extract zero-ended bit field 

20 OPEN "TT: M FOR INPUT AS FILE #1% ! Open terminal as a file 

INPUT #1%. "HEX>"; HEXINl ! Prompt for input 

STAn*OTS$CVT_TZ_L(HEXIN$, BINARYy.) ! Convert to longword 
IF (STAT% AND 1 %) <> 1% ! Failed? 

THEN 

PRINT "Conversion failed, decimal status ";STATy, 

GO TO 20 ! Try again 

ELSE 

PRINT HEXIN$, 

PRINT STR$(LIB$EXTZV(Ny., 1%, BINARYy.)); 

for Ny.=3iy to oy. step - 1 % 


9.3.2 Integer and Floating-Point Procedures 

Integer and floating-point procedures give a high-level language program 
access to the corresponding machine instructions. For a complete description 
of these instructions, see the VAX-11 Architecture Reference Manual. Table 9-4 
lists the integer and floating-point procedures. 


Table 9-4 Integer and Floating-Point Procedures 


Entry Point 

Function 


Evaluate Polynomial Procedures 


LIB$POLYF 

Evaluates F_floating polynomial using Horner's method 

LIB$POLYD 

Evaluates D_floating polynomial using Horner's 

method 

LIBSPOLYG 

Evaluates G_floating polynomial using Horner's 

method 

LIBSPOLYH 

Evaluates H_floating polynomial using Horner's 

method 

Extended Multiply and Integerize Procedures 


LIB$EMODF 

Calculates F_floating modulus 


LIBSEMODD 

Calculates D_floating modulus 


LIBSEMODG 

Calculates G_floating modulus 


LIBSEMODH 

Calculates H_floating modulus 


LIBSEMUL 

Multiplies integers with extended precision 


LIBSEDIV 

Divides integers with extended precision 
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9.3.3 Queue Access Procedures 

A queue is a doubly linked list. A Run-Time Library procedure specifies 
a queue entry by its address. Two longwords, a forward link and a 
backward link, define the location of the entry in relation to the preceding 
and succeeding entries. A self-relative queue is a queue in which the 
links between entries are displacements; the two longwords represent the 
displacements of the current entry's predecessor and successor. The VAX 
instructions INSQHI, INSQTI, REMQHI, and REMQTI allow you to insert 
and remove an entry at the head or tail of a self-relative queue. Each queue 
instruction has a corresponding Run-Time Library procedure. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the 
current program is doing so. Since the operation requires changing two 
pointers at the same time, a high-level language cannot perform this 
operation without calling the Run-Time Library queue access procedures. 

When you use these procedures, cooperating processes can communicate 
without further synchronization and without danger of being interrupted, 
either on a single processor or in a multiprocessor environment. The queue 
access procedures are also useful in an AST environment; they allow you 
to add or remove an entry from a queue without being interrupted by an 
asynchronous system trap. 

The remove queue instructions (REMQHI or REMQTI) return the address 
of the removed entry. Some languages, such as BASIC, COBOL, and 
FORTRAN, do not provide a mechanism for accessing an address returned 
from a procedure. Furthermore, BASIC and COBOL do not allow procedures 
as arguments. 

Table 9-5 lists the Queue Access Procedures. 


Table 9-5 Queue Access Procedures 


Entry Point 

Function 

LIBSINSQHI 

Inserts queue entry at head 

LIBSlNSQTI 

Inserts queue entry at tail 

LIBS REMQHI 

Removes queue entry at head 

LIBSREMQTI 

Removes queue entry at tail 


Examples 

LIBSINSQHI 

In BASIC and FORTRAN, queues can be quadword aligned in a named 
COMMON block by using a linker option file to specify PSECT alignment. 
The Run-Time Library procedure LIB$GET_VM returns memory that is 
quadword aligned. Therefore, you should use LIB$GET_VM to allocate the 
virtual memory for a queue. For instance, to create a COMMON block called 
QUEUES, use the LINK command with the FILE/OPTIONS qualifier, where 
FILE.OPT is a linker option file containing the line: 

PSECT = QUEUES, QUAD 
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For a FORTRAN application using processor-shared memory: 

INTEGER*4 FUNCTION INSERT.Q (QENTRY) 

COMMON/QUEUES/QHEADER 
INTEGER*4 QENTRY(10), QHEADER(2) 

INSERT.Q = LIB$INSQHI (QENTRY, QHEADER) 

RETURN 

END 

A BASIC application using processor-shared memory: 

COM (QUEUES) QENTRY'/,(9) , QHEADER'/,(1) 

EXTERNAL INTEGER FUNCTION LIB$INSQHI 

IF LIBIINSQHI (QENTRY'/,() BY REF, QHEADER'/,() BY REF) AND 17. 
THEN GOTO 1000 


1000 REM INSERTED OK 


LIBSREMQHI 


In FORTRAN, the address of the removed queue entry can be passed to 
another procedure as an array using the %VAL built-in function. In the 
following example, queue entries are ten longwords including the two 
longword pointers at the beginning of each entry. 


COMMON/QUEUES/QHEADER 

INTEGER*4 QHEADER(2), ISTAT 

ISTAT = LIB$REMQHI (QHEADER, ADDR) 

IF (ISTAT) THEN 

CALL PROC C/.VAL (ADDR)) ! Process removed entry 
GO TO ... 

ELSE IF (ISTAT .EQ. '/.LOC(LIB$_QUEWASEMP) ) THEN 

GO TO ... ! Queue was empty 

ELSE IF 


END IF 


! Secondary interlock failed 


END 

SUBROUTINE PROC (QENTRY) 
INTEGER*4 QENTRY(10) 


RETURN 

END 


9.3.4 Character String Procedures 

The character string procedures give a high-level language program access to 
the corresponding VAX machine instructions. For a complete description of 
these instructions, see the VAX-11 Architecture Reference Manual. For each 
instruction, the VAX-11 Architecture Reference Manual specifies the contents of 
all the registers after the instruction executes. The corresponding Run-Time 
Library procedures do not make the contents of all the registers available to 
the calling program. 
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Table 9-6 Character String Procedures 


Entry Point 

Function 

Character String 

Manipulation Procedures 

LIBSLOCC 

Locates a character in a string 

LIB$MATCHC 

Returns the relative position of a substring 

LIBSSCANC 

Scans characters 

LIB$SKPC 

Skips characters 

LIBSSPANC 

Spans characters 

LIB$M0VC3 

Moves characters 

LIB$M0VC5 

Moves characters and fills 

Character String 

Translation Procedures 

LIBSMOVTC 

Moves translated characters 

LIBSMOVTUC 

Move translated characters until specified character is 
encountered 


Section 5 describes STR$ string manipulation procedures. 

Example 

This COBOL program uses LIB$LOCC to return the position of a given letter 
of the alphabet. 

IDENTIFICATION DIVISION. 

PROGRAM-ID. LIBLOC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 


WORKING-STORAGE SECTION. 


01 

SEARCH-STRING 

PIC X(26) 

VALUE "ABCDEFGHIJKLMNOPQRSTUVWXYZ" 

01 

SEARCH-CHAR 

PIC X. 

01 

IND-POS 

PIC 9(9) USAGE IS COMP. 

01 

DISP-IND 

PIC 9(9). 

PROCEDURE DIVISION. 



001-MAIN. 

MOVE SPACE TO SEARCH-CHAR. 

DISPLAY M 

DISPLAY "ENTER SEARCH CHARACTER: " WITH NO ADVANCING. 

ACCEPT SEARCH-CHAR. 

CALL "LIB$LOCC" 

USING BY DESCRIPTOR SEARCH-CHAR, SEARCH-STRING 
GIVING IND-POS. 

IF IND-POS = ZERO 
DISPLAY 

"CHAR ENTERED (" SEARCH-CHAR ") NOT A VALID SEARCH CHAR" 
STOP RUN. 

MOVE IND-POS TO DISP-IND. 

DISPLAY 

"SEARCH CHAR (" SEARCH-CHAR ") WAS FOUND IN POSITION " 
DISP-IND. 

GO TO 001-MAIN. 
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9.3.5 Miscellaneous Instruction Procedures 

Table 9-7 Miscellaneous Instruction Procedures 

Entry Point Function 

LIBSCALLG Calls a procedure using an array argument list 

LIBSCRC Computes a Cyclic Redundancy Check 

LIB$CRC_TABLE Constructs a table for a Cyclic Redundancy Check 


LIBSCALLG 

LIB$CALLG allows your program access to the CALLG instruction. This 
instruction calls a procedure using an argument list stored as an array in 
memory, as opposed to the CALLS instruction, in which the argument list is 
pushed on the stack. 

LIBSCRC 

LIBSCRC allows your high-level language program to use the CRC 
instruction, which calculates the Cyclic Redundancy Check. This instruction 
is used to check the integrity of a data stream by comparing its state at the 
sending point and the receiving point. Each character in the data stream 
is used to generate a value based on a polynomial. The values for each 
character are then added together. This operation is performed at both ends 
of the data transmission, and the two result values compared. If the results 
disagree, then an error occurred during the transmission. 

LIB$CRC_TABLE takes a polynomial as its input and builds the table that 
LIBSCRC uses to calculate the CRC. You must specify the polynomial to be 
used. 

For further details see the VAX-11 Architecture Reference Manual. 


9.4 Processwide Resource Allocation Procedures 

This section discusses procedures that allocate processwide resources to a 
single VMS process. The processwide resources discussed here are: VMS 
local event flags, and BASIC and FORTRAN logical unit numbers (LUNs). 
The resource-allocation procedures are provided so that user procedures can 
use the processwide resources without conflicting with one another. 

In general, you must use Run-Time Library resource allocation procedures 
when your program needs processwide resources. This allows Run-Time 
Library procedures, DIGITAL-supplied procedures, and user procedures that 
you write to perform properly together within a process. 

If your called procedure includes a call to any Run-Time Library procedure 
that frees a processwide resource, and that called procedure fails to execute 
normally, the resource will not be freed. Thus your procedure should 
establish a condition handler that frees the allocated resource before 
resignaling or unwinding. Section 7 describes condition handling. 
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Table 9-8 lists the processwide resource allocation procedures. 


Table 9-8 Processwide Resource Allocation Procedures 


Entry Point 

Function 

BASIC/FORTRAN Logical Unit Allocation 

LIB$FREE_LUN 

Deallocates a specific logical unit number 

LIB$GET_LUN 

Allocates next arbitrary logical unit number 

Event Flag Allocation 

LIB$FREE_EF 

Frees a local event flag 

LIB$GET_EF 

Allocates a local event flag 

LIB$RESERVE_EF 

Reserves a local event flag 


9.4.1 Allocating Logical Unit Numbers 

BASIC and FORTRAN use a logical unit number (LUN) to define the file 
or device a program uses to perform input and output. For a procedure 
to be modular, it does not need to know the unit numbers being used by 
other procedures running at the same time. For this reason, logical units 
are allocated and deallocated at run time. You can use LIB$GET_LUN and 
LIB$FREE_LUN to obtain the next available number. This ensures that your 
BASIC or FORTRAN procedure will not use a logical unit that is already 
being used by a calling program. Therefore, you should use this procedure 
whenever your program calls or is called by another program which may also 
allocate LUNs. Logical unit numbers 100 to 119 are available to modular 
procedures through these entry points. 

To allocate a logical unit number, call LIB$GET_LUN and use the value 
returned as the logical unit number for your I/O statements. If no LUNs are 
available, an error status is returned and the logical unit is set to -1. When 
the program unit exits, it should use LIB$FREE_LUN to free any logical 
unit numbers that have been allocated by LIB$GET_LUN. If it does not, the 
available pool of numbers can be used up. 

If your called procedure contains a call to LIB$ FREE—LUN to free the LUNs 
upon exit, and your procedure fails to execute normally, the LUNs will not be 
freed. For this reason, you should make sure to establish a condition handler 
to call LIB$FREE_LUN before resignaling or unwinding. Otherwise, the 
allocated LUN is lost until the image exits. 


9.4.2 Allocating Event Flag Numbers 

LIB$GET_EF and LIB$FREE_EF operate in a similar way to LIB$GET_LUN 
and LIB$FREE__LUN. They cause local event flags to be allocated and 
deallocated at run time, so that your procedure remains independent of other 
procedures executing in the same process. 

Local event flags numbered 32 to 63 are available to your program. 

These event flags allow procedures to communicate and synchronize their 
operations. If you use a specific event flag in your procedure, another 
procedure may attempt to use the same flag, and the flag will no longer 
function as expected. Therefore, you should call LIB$GET_EF to obtain the 
next arbitrary event flag and LIB$FREE__EF to return it to the storage pool. 
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You can obtain a specific event flag number by calling LIB$RESERVE_EF. 
This procedure takes as its argument the event flag number to be allocated. 


Performance Measurement Procedures 

The Run-Time Library timing facility consists of four procedures to store 
count and timing information, display the requested information, and 
deallocate the storage. Table 9-9 lists these procedures and their functions. 


Table 9-9 Performance Measurement Procedures 


Entry Point 

Function 

LIB$INIT_TIMER 

Stores the values of the specified times and counts in static 
or heap storage, depending on the value of the procedure's 
argument 

LIB$SHOW_TIMER 

Gets and formats for output the specified times and counts 
accumulated since the last call to LIB$INIT_TIMER 

LIB$ST AT_TIMER 

Gets one of the times and counts since the last call to 
LIB$INIT_TIMER and returns it as an unsigned quadword or 
longword 

LIB$FREE_TIMER 

Frees the storage allocated by LIB$INIT_TIMER 


Using these procedures, you can access the following statistics: 

• Elapsed time 

• CPU time 

• Buffered I/O count 

• Direct I/O count 

• Page faults 

LIB$SHOW_TIMER and LIB$STAT_TIMER are relatively simple tools for 
testing the performance of a new application. To obtain more detailed 
information, use the VAX/VMS system services SYS$GETTIM (Get Time) and 
SYS$GETJPI (Get Job/Process Information). 

The simplest way to use the Run-Time Library procedures is to call 
LIB$INIT_TIMER with no arguments at the beginning of the portion of 
code to be monitored. This will cause the statistics to be placed in OWN 
storage. Then call LIB$SHOW_TIMER, again with no arguments, at the end 
of this period, to get the statistics from OWN storage. 

If you want a particular statistic, you must include a code argument with a 
call to LIB$SHOW_TIMER or LIB$STAT_TIMER, as shown in Table 9-10. 
LIB$ SHOW-TIMER returns the specified statistic(s) in formatted form and 
sends them to SYS$OUTPUT. On each call, LIB$STAT_TIMER returns one 
statistic to the calling program as an unsigned longword or quadword value. 
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Table 9-10 The Code Argument in LIB$SHOW_TIMER and 
LIB$STAT_TIMER 


Value of 
code 

Statistic 

Format — 

LIB$SHOW_ 

TIMER 

Format — 

LIB$STAT_ 

TIMER 

1 

Elapsed real time 

hhhh:mm:ss.cc 

Quadword, in 
system time 
format 

2 

Elapsed CPU time 

hhhh:mm:ss.cc 

Longword, in 

10-millisecond 

increments 

3 

Count of buffered I/O 
operations 

nnnn 

Longword 

4 

Count of direct I/O 
operations 

nnnn 

Longword 

5 

Count of page faults 

nnnn 

Longword 


When you call LIB$INIT_TIMER, you must use the optional handler 
argument only if you want to keep several sets of statistics simultaneously. 
This argument points to a block in heap storage where the statistics are to 
be stored. You only need to call LIB$FREE_TIMER if you have specified 
handler in LIB$INIT_TIMER and you wish to deallocate all heap storage 
resources. In most cases, the implicit deallocation when the image exits will 
be sufficient. 

LIB$STAT_TIMER returns only one of the five statistics for each call, and 
returns that statistic in the form of an unsigned quad word or longword. 
LIB$SHOW_TIMER returns the virtual address of the stored information, 
which BASIC cannot directly access. Therefore a BASIC program must 
call LIB$STAT_TIMER and format the returned statistics, as the following 
example demonstrates. 

Example 

The following BASIC example uses the Run-Time Library performance 
analysis procedures to obtain timing statistics. It then calls the $ASCTIM 
system service to translate the 64-bit binary value returned by LIB$STAT_ 
TIMER into an ASCII text string. 
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100 


200 


300 


400 


450 

500 

550 

050 


700 

750 

800 


810 


900 

32765 

32766 

32767 


EXTERNAL INTEGER FUNCTION LIB$INIT_TIMER 
EXTERNAL INTEGER FUNCTION LIB$STAT_TIMER 
EXTERNAL INTEGER FUNCTION LIB$FREE.TIMER 
EXTERNAL INTEGER CONSTANT SS$_N0RMAL 

DECLARE LONG COND.VALUE. RANDOM.SLEEP 
DECLARE LONG CODE, HANDLE 
DECLARE STRING TIME_BUFFER 
HANDLE = 0 

TIME.BUFFER = SPACE!(50%) 

MAP (TIMER) LONG ELAPSED.TIME, FILL 

MAP (TIMER) LONG CPU.TIME 

MAP (TIMER) LONG BUFIO 

MAP (TIMER) LONG DIRIO 

MAP (TIMER) LONG PAGE.FAULTS 

PRINT "This program returns information about:" 

PRINT "Elapsed time (1)" 

PRINT "CPU time (2)" 

PRINT "Buffered I/O (3)" 

PRINT "Direct I/O (4)" 

PRINT "Page faults (5)" 

PRINT "Enter zero to exit program" 

PRINT "Enter a number from one to" 

PRINT "five for performance information" 

INPUT "One, two, three, four, or five"; CODE 
PRINT 

GOTO 32766 IF CODE = 0 

COND.VALUE = LIB$INIT_TIMER( HANDLE ) 

IF (COND.VALUE <> SS$_NORMAL) THEN PRINT "Error in initialization" 

GOTO 32767 

A = 0 ! 

FOR I * 1 to 100000 ! This code merely uses some CPU time 

A ® A + 1 ! 

NEXT I ! 

COND.VALUE = LIB$STAT.TIMER( CODE, ELAPSED.TIME, HANDLE ) 

IF (COND.VALUE <> SS$_NORMAL) THEN PRINT "Error in statistics routine" 
GOTO 32767 

GOTO 810 IF CODE <> 1% 

CALL SYSIASCTIM ( . TIME.BUFFER, ELAPSED.TIME, 1% BY VALUE) 

PRINT "Elapsed time: "; TIME.BUFFER 

PRINT "CPU time in seconds: "; .01 * CPU.TIME IF CODE = 2% 

PRINT "Buffered I/O: ";BUFIO IF CODE = 3% 

PRINT "Direct I/O: ";DIRIO IF CODE = 4% 

PRINT "Page faults: ";PAGE.FAULTS IF CODE * 5% 

PRINT 

GOTO 400 

COND.VALUE = LIB$FREE_TIMER( HANDLE ) 

IF (COND.VALUE <> SSl.NORMAL) THEN PRINT "Error in LIBlFREE.TIMER" 

GOTO 32767 


END 
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9.6 Output Formatting Control Procedures 

Table 9-11 lists the Run-Time Library procedures that customize output. 


Table 9-11 Procedures for Customizing Output 


Entry Point 

Function 

LIBSCURRENCY 

LIB$DIGIT_SEP 

LIB$LP_LINES 

LIB$RADIX_POINT 

Defines the default currency symbol for process 

Defines the default digit separator for process 

Defines the process default size for a printed page 

Defines the process default radix point character 


LIB$CURRENCY, LIB$DIGIT_SEP, LIB$LP_LINES, and LIB$RADIX_POINT 
allow you to customize output. Using them, you can define the logical names 
SYS$CURRENCY, SYS$DIGIT_SEP, SYS$LP_LINES, and SYS$RADIX_ 
POINT to specify your own currency symbol, digit separator, radix point, 
or number of lines per printed page. Each of these procedures works by 
attempting to translate the associated logical name as a process, group, or 
system logical name. If you have redefined a logical name for a specific local 
application, then the translation succeeds, and the procedure returns the 
value that corresponds to the option you have chosen. If the translation fails, 
the procedure returns a default value provided by the Run-Time Library, as 
follows: 

$ SYSSCURRENCY 
SYS$DIGIT_SEP 
SYS$RADIX_POINT 
66 SYS$LP_LINES 

For example, if you wish to use the British pound sign as the currency symbol 
within your process, but wish to leave the dollar sign as the system's default, 
define SYSSCURRENCY to be in your process logical name table. After this, 
any call to LIB$CURRENCY within your process returns while any call 
outside your process returns 

You can use LIB$LP_LINES to monitor the current default length of the line 
printer page. You can also supply your own default length for the current 
process. United States standard paper stock permits 66 lines on each physical 
page. 

If you are writing programs for a utility that formats a listing file to be 
printed on a line printer, you can use LIB$LP_LINES to make your utility 
independent of the default page length. Your program can use LIB$LP_ 
LINES to obtain the current length of the page. It can then calculate the 
number of lines of text per page by subtracting the lines used for margins and 
headings. 

The following is one suggested format: 

1 Three lines for the top margin 

2 Three lines for bottom margin 
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3 Three lines for listing heading information, consisting of: 
a Language-processor identification line 
b Source-program identification line 
c One blank line 


9.7 


Date/Time Utility Procedures 

The Run-Time Library provides the date/time utility procedures for languages 
that do not have built-in time and date functions, and for particular 
applications that require the time or date in a different format from the one 
that the language supplies. In general, it is simpler to call the Run-Time 
Library routines for the system date and time than to call a system service. 
Table 9-12 lists the Date/Time Utility Procedures. 


Table 9-12 Date/Time Utility Procedures 


Entry Point 
LIB$DATE_TIME 

LIB$DAY 

LIB$DAY_OF_ 

WEEK 


Function 

Returns the system date and time in the semantics of the 
user's string 

Returns the number of days since November 17, 1858 

Returns the numeric day of the week for either an input time 
value or the current day. 


The LIB$ facility of the Run-Time Library provides three date/time utility 
procedures: 

Returns the VAX/VMS system date and time in the 
semantics of a string that you provide, using a string 
descriptor. 

Returns the number of days since the system zero date 
of November 17, 1858. This procedure takes one 
required argument and two optional arguments: 

• The address of a longword to contain the number of 
days since the system zero date. 

• A quadword passed by reference containing a time 
in system time format to be used instead of the 
current system time (optional). 

• A longword integer to contain the number of 10 
millisecond units since midnight (optional). 

LIB$DAY_OF_WEEK Returns the numeric day of the week for an input time 

value. If zero is the input time value, the current day 
of the week is returned. The days are numbered 1 
through 7, with Monday as day 1 and Sunday as day 7. 

The Run-Time Library also contains a routine, LIB$SYS_ASCTIM, that 
provides an interface between higher-level languages and the $ASCTIM 
system service. 


LIB$DATE_TIME 

LIBSDAY 
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Examples 

The following BASIC code fragment shows how you could use LIB$DAY to 
obtain the number of days between two dates. 

100 EXTERNAL INTEGER FUNCTION SYSSBINTIM, LIB$DAY 
110 COM INTEGER USER.TIME, FILL 
120 DECLARE INTEGER RET.STATUS 
300 DEF FNDAY'/, (DAY_TIME$) & 

\ RET.STATUS = SYS$BINTIM(DAY_TIME$.USER.TIME) & 

\ IF (RET.STATUS AND 1%) = 0*/. THEN & 

CALL LIB$ST0P(RET.STATUS BY VALUE) 

320 RET.STATUS = LIB$DAY(DAY_TMP*/..USER.TIME) A 

\ IF (RET.STATUS AND 17.) = 0% THEN & 

CALL LIB$ST0P(RET.STATUS BY VALUE) 

330 FNDAY7. = DAY.TMP7, A 

\ FNEND 

400 INPUT "Enter two dates (dd-MMM-yyyy)";DAY1$,DAY2$ 

410 PRINT "Number of days between is"; A 
FNDAY7, (DAY2$) - FNDAY7,(DAY1$) 

999 END 


9.8 Miscellaneous Interface Procedures 

There are several other Run-Time Library procedures that permit high-level 
access to components of VAX/VMS. Table 9-13 lists these procedures and 
their functions. The sections that follow give further details about some of 
these procedures. 

Table 9-13 Miscellaneous Interface Procedures 

Entry Point Function 


Indicate AST 

LIB$AST_IN_PROG Indicates whether an asynchronous system trap is 

in progress 

Assign an I/O Channel with a Mailbox 

LIB$ASN_WTH_MBX Assigns an I/O channel and associates it with a 

mailbox 


Create a Directory 

LIB$CREATE_DIR Creates a directory or subdirectory 

Find Global Symbol 

LIB$FIND_IMAGE_SYMBOL Reads a global symbol from the shareable image 

file and dynamically activates a shareable image 
into the P0 address space of a process 


Variable-Length Integer Arithmetic Procedures 

LIBSADDX Performs addition on signed two's complement 

integers of arbitrary length (multiple-precision 
addition) 

LIBSSUBX Performs subtraction on signed two's 

complement integers of arbitrary length 
(multiple-precision subtraction) 
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Table 9-13 (Cont.) Miscellaneous Interface Procedures 


Entry Point 

Function 

File Search Procedures 


LIB$FILE_SCAN 

Finds filenames given RMS FAB 

LIB$FILE_SCAN_END 

End of file scan 

LIB$FIND_FILE 

Finds filenames given string 

LIB$FIND_FILE_END 

End of find file 

Binary Tree Procedures 

LIB$INSERT_TREE 

Inserts an element in a binary tree 

LIB$LOOKUP_TREE 

Finds an element in a binary tree 

LIB$TRAVERSE_TREE 

Traverses a binary tree 

Common I/O Procedures 

LIB$GET_COMMON 

Gets a record from the process's COMMON 
storage area 

LIB$PUT_COMMON 

Puts a record to the process's COMMON storage 
area 


9.8.1 Indicating Asynchronous System Trap in Progress 

An asynchronous system trap (AST) is a VAX/VMS mechanism for providing 
a software interrupt when an external event occurs, such as the user typing 
CTRL/C. When an external event occurs, VAX/VMS interrupts the execution 
of the current process and calls a procedure that you supply. While that 
procedure is active, the AST is said to be in progress, and the process is said 
to be executing at AST level. When your AST procedure returns control to 
the original process, the AST is no longer active and execution continues 
where it left off. 

LIB$AST_IN_PROG indicates to the calling program whether an AST 
is currently in progress. Your program can call LIB$AST_JN_PROG to 
determine whether it is executing at AST level, and then take appropriate 
action. This procedure is useful if you are writing AST-reentrant code. 


9.8.2 Assigning an I/O Channel Along with a Mailbox 

A mailbox is a virtual device used for communication between processes. 

A channel is the communication path that a process uses to perform I/O 
operations to a particular device. LIB$ASN_WTH__MBX assigns a channel to 
a device and associates a mailbox with the device. 

Normally, a process calls the $CREMBX system service to create a mailbox 
and assign a channel and logical name to it. In the case of a temporary 
mailbox, this service places the logical name corresponding to the mailbox in 
the group logical name table. This implies that any process running in the 
same group and using the same logical name uses the same mailbox. 
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Sometimes this is not desirable. For example, when a program connects 
explicitly with another process across a network, the program uses a mailbox 
to obtain the data confirming the connection and to store the asynchronous 
messages from the other process. If that mailbox is shared with other 
processes in the same group, there is no way to determine which messages 
are intended for which processes; the processes will read each other's 
messages, and the original program will not receive the correct information 
from the cooperating process across the network link. 

LIB$ASN_WTH_MBX avoids this situation by associating the physical 
mailbox name with the channel assigned to the device. To create a temporary 
mailbox for itself and other processes cooperating with it, your program calls 
LIB$ASN_WTH_MBX. The Run-Time Library procedure assigns the channel 
and creates the temporary mailbox by using the system services $GETCHN, 
$ASSIGN, and $CREMBX. Instead of a logical name, the mailbox is identified 
by a physical device name of the form MBcu. The elements which make up 
this device name are as follows: 

MB indicates that the device is a mailbox 
c is the controller 

u is the unit number 

The procedure returns this device name to the calling program, which 
then must pass the mailbox channel to the other program(s) with which it 
cooperates. In this way, the cooperating processes access the mailbox by its 
physical name, instead of by its group-wide logical name. 

The calling program passes the procedure a device name, which specifies 
the device to which the channel is to be assigned. For this argument (called 
dev-nam), you may use a logical name. If you do so, the procedure attempts 
one level of logical name translation. 

The privilege restrictions and process quotas required for using this procedure 
are those required by the $GETCHN, $CREMBX, and $ ASSIGN system 
services. 


9.8.3 Create a Directory or Subdirectory 

LIB$CREATE_DIR creates a directory or subdirectory. The calling program 

must specify the directory specification in standard RMS format. This 

directory specification may also contain a disk specification. 

In addition to the required directory specification argument, LIB$CREATE_ 

DIR takes the following five optional arguments: 

• User Identification Code (UIC) of the owner of the created directory or 
subdirectory 

• Protection enable mask 

• Protection value mask 

• Maximum number of versions allowed for files created in this directory or 
subdirectory 

• Relative volume number within the volume set on which the directory or 
subdirectory is to be created 

See Part II of this manual for a complete description of LIB$CREATE_DIR. 
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9.8.4 File Searching Procedures 

The Run-Time Library provides two procedures that your program can call 
to search for a file and two procedures that your program can call to end a 
search sequence. 

• When you call LIB$FILE_SCAN with a wildcard file specification and an 
action routine, the procedure calls the action routine for each file and/or 
error found in the wildcard sequence. LIB$FILE_SCAN allows the search 
sequence to continue even though certain errors are present. 

• When you call LIB$FIND_FILE with a wildcard file specification, it finds 
the next file specification that matches the wildcard specification. 

In addition to the wildcard file specification, which is a required argument, 
LIB$FIND_FILE takes the following four optional arguments: 

• The default specification. 

• The related specification. 

• The RMS secondary status value from a failing RMS operation. 

• A longword containing two flag bits. If bit 1 is set, LIB$FIND_FILE 
performs temporary defaulting for multiple input files and the related 
specification argument is ignored. See Part II of this manual for a 
complete description of LIB$FIND_FILE in template format. 

LIB$FIND_FILE_END is called once after each call to LIB$FIND_FILE in 
interactive use. LIB$FIND_FILE_END prevents the temporary default values 
retained by the previous call to LIB$FIND_FILE from affecting the next file 
specification. 

LIB$FILE_SCAN has an optional context argument which is used to perform 
temporary defaulting for multiple input files. For example, a command such 
as: 

$C0PY [smith]A,B,C * 

would want to specify A, B, and C in successive calls, retaining context, so 
that portions of one file specification would affect the next file specification. 

LIB$FILE_SCAN_END is called once after each sequence of calls to 
LIB$FILE_SCAN. LIB$FILE_SCAN_END performs a parse of the null 
string to deallocate saved RMS context and to prevent the temporary default 
values retained by the previous call to LIB$FILE_SCAN from affecting 
the next file specification. For instance, in the above example, LIB$FILE_ 
SCAN-END should be called after the C file specification is parsed, so 
that specifications from the $COPY files do not affect file specifications in 
subsequent commands. 

The following BLISS example illustrates the use of LIB$FIND_FILE. It 
prompts for a file specification and default specification. The default 
specification indicates the default information for the file for which you 
are searching. Once the procedure has searched for one file, the resulting 
file specification determines the related file specification and the default file 
specification for the next search. LIB$FIND_FILE_END is called at the end 
of this BLISS program to deallocate the virtual memory used by LIB$FIND_ 
FILE. 
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7.TITLE 'FILE.EIAMPLE1 
MODULE FILE.EXAMPLEl( 

IDENT 
MAIN 
) * 

BEGIN 

‘/.SBTTL ' Declarations' 

! + 

! SWITCHES: 

; - 

SWITCHES ADDRESSING.MODE (EXTERNAL = GENERAL, NONEXTERNAL = WORD.RELATIVE); 


- Sample program using LIB$FIND_FILE' 

! Sample program using LIB$FIND_FILE 

= ' 1 - 001 ', 

= EXAMPLE.START 


! + 

! TABLE OF CONTENTS: 

i - 



FORWARD ROUTINE 
EXAMPLE.START; 

INCLUDE FILES: 


Main program 


LIBRARY *SYS$LIBRARY:STARLET.L32'; ! System symbols 


! + 

! Define facility-specific messages from shared system messages. 
! - 

$SHR_MSGDEF(CLI,3,LOCAL, 

(PARSEFAIL,WARNING)); 



! + 

! EXTERNAL REFERENCES: 

i - 

EXTERNAL ROUTINE 
LIB$GET_INPUT, 
LIB$FIND_FILE, 
LIB$FIND_FILE_END, 
LIB$PUT_OUTPUT, 
STR$COPY_DX; 


LITERAL 

TRUE = 1, 
FALSE = 0; 


! Read from SYS$INPUT 
! Wild card scanning routine 

! End find file 

! Write to SYS$OUTPUT 
! String copier 

! Success 
! Failure 



%SBTTL 'EXAMPLE.START - Sample program main routine'; 

ROUTINE EXAMPLE.START = 

BEGIN 
! + 

! This program reads a file specification and default file 
! specification from SYS$INPUT. It then prints all the files that 
! match that specification and prompts for another file specification. 

! After the first file specification no default specification is requested, 
! and the previous resulting file specification becomes the related 
! file specification. 


i - 

LOCAL 

LINEDESC 


SBBLOCK[DSC$C_S_BLN] 


RESULT.DESC : 
CONTEXT, 
DEFAULT.DESC 
RELATED.DESC 
HAVE.DEFAULT, 
STATUS; 


$BBL0CK[DSC$C_S_BLN], 

SBBLOCK[DSC$C_S_BLN] 
$BBL0CK[DSC$C_S_BLN] 


String desc. for input line 
String desc. for result file 
LIB$FIND_FILE context pointer 
String desc. for default spec 
String desc. for related spec 



! Make all string descriptors dynamic. 

I - 

CH$FILL(0,DSC$C_S.BLN,LINEDESC); 

LINEDESC[DSC$B_CLASS] = DSC$K_CLASS_D; 
CH$M0VE(DSC$C_S_BLN.LINEDESC,RESULT.DESC); 
CH$MOVE(DSC$C_S_BLN.LINEDESC,DEFAULT.DESC); 
CHlMOVE(DSC$C_S_BLN,LINEDESC,RELATED.DESC); 
HAVE.DEFAULT = FALSE; 

CONTEXT = 0; 
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! Read file specification, default file specification, and 
! related file specification. 

i - 

WHILE (STATUS * LIB$GET_INPUT(LINEDESC, 

(DESCRIPTOR('FILE SPECIFICATION: '))) NEQ RMS(.E0F 

DO BEGIN 

IF NOT .STATUS 

THEN SIGNAL.STOPC.STATUS); 

! + 

! If default file spec was not obtained, do so now. 

! - 

IF NOT .HAVE.DEFAULT 
THEN BEGIN 

STATUS = LIB$GET_INPUT(DEFAULT.DESC, 

(DESCRIPTOR('DEFAULT FILE SPECIFICATION: ')); 

IF NOT .STATUS 

THEN SIGNAL.STOPC.STATUS); 

HAVE.DEFAULT = TRUE; 


! CALL LIB(FIND.FILE until RMS(_NMF (no more files) is returned. 
! If an error other than RMS(_NMF is returned, it is signaled. 

! Print out the file specification if the call is successful. 

WHILE (STATUS = LIB(FIND.FILE(LINEDESC.RESULT.DESC,CONTEXT, 
DEFAULT.DESC,RELATED.DESC)) NEQ RMS(.NMF 

DO IF NOT .STATUS 

THEN SIGNAL(CLK.PARSEFAIL.l,RESULT.DESC. .STATUS) 

ELSE LIB(PUT_OUTPUT(RESULT.DESC); 


! Make this resultant file spec the related file spec for next file. 

STR(COPY_DX(RELATED.DESC,LINEDESC); 

END; ! End of loop 

! reading file spec 

! ♦ 

! Call LIB(FIND.FILE.END to deallocate the virtual memory used by LIB(FIND.FILE. 

! Note that we do this outside of the loop. Since the MULTIPLE bit of the 
! optional user flags argument to LIB(FIND.FILE wasn't used, it is not 
! necessary to call LIB(FIND_FILE_END after each call to LIB(FIND_FILE. 

! (The MULTIPLE bit would've caused temporary defaulting for multiple input 
! files.) 

STATUS * LIB(FIND_FILE_END (CONTEXT); 

IF NOT .STATUS 

THEN SIGNAL.STOP (.STATUS); 

RETURN TRUE 
END; 

END 

ELUDOM 

This BLISS example illustrates LIB$FILE_SCAN and LIB$FILE_SCAN_END. 

5CTITLE 'FILE.EXAMPLE2 - Sample program using LIB(FILE_SCAN' 

MODULE FILE.EXAMPLEl( ! Sample program using LIB(FILE.SCAN 

IDENT = 'i-001', 

MAIN = EXAMPLE.START 

) « 

BEGIN 

XSBTTL 'Declarations' 

• + 

! SWITCHES: 

; - 

SWITCHES ADDRESSING.MODE (EXTERNAL = GENERAL, 

NONEXTERNAL = WORD.RELATIVE); 


! End of main program 
! End of module 
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TABLE OF CONTENTS: 


FORWARD ROUTINE 
EXAMPLE.START, 
SUCCESS.RTN, 
ERROR.RTN; 


! Main program 
! Success action routine 
! Error action routine 


! INCLUDE FILES: 

j - 

LIBRARY 'SYSlLIBRARY:STARLET.L32'; ! System symbols 

! ♦ 

! Define VMS block structures (BLOCK[.BYTE]). 

! - 

STRUCTURE 

BBLOCK [0. P. S. E; N] = 

[N] 

(BBLOCK +0) <P. S. E>; 

! ♦ 

! EXTERNAL REFERENCES: 


! Read from SYSlINPUT 
! Wild card scanning routine 
End of file scan 
! Write to SYSlOUTPUT 


EXTERNAL ROUTINE 
LIB$GET_INPUT, 

LIBlFILE.SCAN, 

LIBlFILE.SCAN.END, 

LIB$PUT_0UTPUT; 

XSBTTL 'EXAMPLE.START - Sample program main routine'; 

ROUTINE EXAMPLE.START * 

BEGIN 
! ♦ 

! This program reads a file specification, default file specification. 
! and related file specification from SYSlINPUT and then displays on 
! SYSIOUTPUT all files which match the specification. 

i - 

LOCAL 

RESULT.BUFFER : VECTOR[NAMlC.MAXRSS.BYTE], 

EXPAND.BUFFER : VECTOR[NAMlC.MAXRSS.BYTE]. 

LINEDESC : BBLOCK[DSClC.S.BLN]. 

RESULT.DESC : BBLOCK[DSClC.S.BLN]. 

DEFAULT.DESC : BBLOCK[DSClC.S.BLN]. 

RELATED.DESC : BBLOCK[DSClC.S.BLN]. 

IFAB : IFAB.DECL, 

INAM : INAM.DECL. 

RELNAM : INAM.DECL, 

STATUS; 


Buffer for resultant 
name string 
Buffer for expanded 
name string 
String descriptor 
for input line 
String descriptor 
for result file 
String descriptor 
for default spec 
String descriptor 
for related spec 
FAB for file.scan 
and a NAM block 
and a related NAM block 
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! Make all descriptors dynamic. 

CH$FILL(0,DSC$C_S_BLN,LINEDESC); 

LINEDESC[DSC$B_CLASS] = DSC$K_CLASS_D; 
CH$M0VE(DSC$C_S_BLN,LINEDESC.RESULT.DESC); 
CH$MOVE(DSC$C_S_BLN,LINEDESC,DEFAULT.DESC); 
CH$M0VE(DSC$C_S_BLN.LINEDESC,RELATED.DESC); 


! Read file specification, default file specification, and related 
! file specification. 

! - 

STATUS = LIB$GET_INPUT(LINEDESC, 

$DESCRIPTOR('File specification: ')); 

IF NOT .STATUS 

THEN SIGNAL.STOP(.STATUS); 

STATUS = LIB$GET_INPUT(DEFAULT_DESC, 

$DESCRIPTOR('Default file specification: ')); 

IF NOT .STATUS 

THEN SIGNAL.STOP(.STATUS); 

STATUS = LIB$GET_INPUT(RELATED_DESC, 

IDESCRIPTORCRelated file specification: ')); 

IF NOT .STATUS 

THEN SIGNAL.STOP(.STATUS); 

! + 

! Initialize the FAB, NAM, and related NAM blocks. 

$FAB_INIT(FAB=IFAB, 

FNS=.LINEDESC[DSC$W_LENGTH]. 

FNA=.LINEDESC[DSC$A_P0INTER], 

DNS=.DEFAULT.DESC[DSC$W_LENGTH], 

DNA=.DEFAULT.DESC[DSC$A_POINTER], 

NAM=INAM); 

$NAM_INIT(NAM=INAM, 

RSS=NAM$C_MAXRSS, 

RSA=RESULT_BUFFER, 

ESS=NAM$C_MAXRSS. 

ESA=EXPAND_BUFFER, 

RLF=RELNAM); 

$NAM_INIT(NAM=RELNAM); 

RELNAM[NAM$B_RSL] = .RELATED.DESC[DSC$W_LENGTH]; 

RELNAM[NAM$L_RSA] = .RELATED.DESC[DSC$A_P0INTER]; 

! + 

! Call LIB$FILE_SCAN. Note that errors need not be checked 
! here because LIB$FILE_SCAN calls error.rtn for all errors. 

! - 

LIB$FILE_SCAN(IFAB,SUCCESS.RTN,ERROR.RTN); 

!♦ 

! Call LIB$FILE_SCAN_END to deallocate virtual memory used for 
! file scan structures. 

| - 

STATUS = LIB$FILE_SCAN_END (IFAB); 

IF NOT .STATUS 

THEN SIGNAL.STOP (.STATUS); 

RETURN 1 

END; ! End of main program 
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ROUTINE SUCCESS.RTN (IFAB : REF BBLOCK) = 

BEGIN 
! ♦ 

! This routine is called by LIB$FILE_SCAN for each file that it 
! successfully finds in the search sequence. 

i 

! Inputs: 
i 

! IFAB Address of a fab 

! 

! Outputs: 

i 

! file specification printed on SYS$OUTPUT 


LOCAL 

DESC : BBLOCK[DSC$C_S_BLN]; ! A local string descriptor 


BIND 

INAM = .IFAB[FAB$L_NAM] : BBLOCK; 

CH$FILL(0,DSC$C_S_BLN,DESC); 

DESC[DSC$W_LENGTH] = .INAM[NAM$B_RSL]; 

DESC[DSC$A_P0INTER] = .INAM[NAM$L_RSA]; 
RETURN LIB$PUT_OUTPUT(DESC) 

END; 


Find NAM block 
from pointer in FAB 
Make static 

string descriptor 
Get string length 
from NAM block 
Get pointer to the string 
Print name on SYS$OUTPUT 
and return 


ROUTINE ERROR.RTN (IFAB : REF BBLOCK) = 
BEGIN 


! This routine is called by LIB$FILE_SCAN for each file specification which 
! produces an error. 

i 

! Inputs: 

j 

! ifab Address of a fab 

i 

! Outputs: 

i 

! Error message is signaled 

LOCAL 

DESC : BBLOCK [DSC$C_S_BLN]; ! A local string descriptor 

BIND 

INAM = .IFAB[FABIL.NAM] : BBLOCK; ! Get NAM block pointer 

! from FAB 

CH$FILL(0,DSC$C_S_BLN,DESC); ! Create static 

! string descriptor 

DESC[DSCSW.LENGTH] = .INAM[NAM$B_RSL]; 

DESC[DSC$A_P0INTER] = .INAM[NAM$L_RSA]; 

! + 

! Signal the error using the shared message PARSEFAIL 
! and the CLI facility code. The second part of the SIGNAL 
! is the RMS STS and STV error codes. 


RETURN SIGNAL((SHR$_PARSEFAIL+3~16),1,DESC, 

.IFAB[FAB$L_STS],.IFAB[FAB$L_STV]) 

END; 

END ! End of module 

ELUDOM 
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9.8.5 Insert Entry in a Balanced Binary Tree 

Three procedures allow you to manipulate the contents of a balanced binary 
tree: 

• LIB$INSERT_TREE adds an entry to a balanced binary tree. 

• LIB$LOOKUP_TREE looks up an entry in a balanced binary tree. 

• LIB$TRAVERSE_TREE calls an action routine for each node in the tree. 

Example 

The following BLISS example illustrates all three of these procedures. The 
program prompts for input from SYS$INPUT and stores each data line as an 
entry in a binary tree. When the user enters end of file (CTRL/Z), the tree 
will be printed in sorted order. The program includes three subroutines: 

• The first allocates virtual memory for a node. 

• The second routine compares a key with a node. 

• The third is called during the tree traversal. It prints out the left and right 
subtree pointers, the current node balance, and the name of the node. 

y.TITLE 'TREE.EXAMPLE - Sample program using binary tree routines' 

MODULE TREE.EXAMPLE( ! Sample program using trees 

IDENT = '1-001'. 

MAIN = TREE.START 
) = 

BEGIN 

y,SBTTL ' Declarations' 

! + 

! SWITCHES: 

; - 

SWITCHES ADDRESSING.MODE (EXTERNAL = GENERAL, NONEXTERNAL = WORD.RELATIVE); 

! + 

! LINKAGES: 

! 

! NONE 

! TABLE OF CONTENTS: 

! - 

FORWARD ROUTINE 
TREE.START. 

ALLOC.NODE, 

COMPARE.NODE, 

PRINT.NODE; 

!♦ 

! INCLUDE FILES: 

! - 

LIBRARY 'SYS$LIBRARY:STARLET.L32'; ! System symbols 

! + 

! Define VMS block structures (BLOCK[.BYTE]). 

i - 

STRUCTURE 

BBLOCK [0, P, S, E; N] = 

[N] 

(BBLOCK +0) <P. S, E>; 


! Main program 

! Allocate memory for a node 
! Compare two nodes 
! Print a node (action routine 
! for LIBITRAVERSE.TREE) 
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! MACROS: 

! - 

MACRO 

NODEIL.LEFT = 0.0,32,07.. 
N0DE$L_RIGHT = 4,0,32,0%, 
N0DE$W_BAL = 8,0,16,0%, 
N0DE$B_NAMLNG = 10,0,8,0%, 
N0DE$T_NAME = 11,0,0,0%; 

LITERAL 

N0DE$C_LENGTH =11; 

! + 

! EXTERNAL REFERENCES: 

i - 

EXTERNAL ROUTINE 
LIB$GET_INPUT, 

LIB$GET_VM, 

LIB$INSERT_TREE, 

LIB$L00KUP_TREE, 

LIB$PUT_OUTPUT, 
LIB$TRAVERSE_TREE, 

STRlUPCASE, 

SYS$FA0; 

7.SBTTL ' TREE_START - Sample program 
ROUTINE TREE.START = 

BEGIN 


! Left subtree pointer in node 
! Right subtree pointer 
! Balance this node 
! Length of name in this node 
! Start of name (variable length) 

! Length of fixed part of node 


! Read from SYSlINPUT 
! Allocate virtual memory 
! Insert into binary tree 
! Lookup in binary tree 
! Write to SYS$OUTPUT 
! Traverse a binary tree 
! Convert string to all upper case 
! Formatted ASCII output routine 

main routine'; 


This program reads from SYSlINPUT and stores each data line 
as an entry in a binary tree. When end of file (CTRL/Z) is 
entered, the tree will be printed in sorted order. 


LOCAL 

NODE : REF BBLOCK, ! 

TREEHEAD, ! 

LINEDESC : BBLOCK [DSClC.S.BLN], ! 
STATUS; 

TREEHEAD =0; ! 

CHIFILL(0,DSCIC.S JBLN,LINEDESC); ! 

LINEDESC[DSCIB.CLASS] = DSC$K_CLASS_D; ! 

! + 

! Read input lines until end of file seen 


WHILE (STATUS = LIB$GET_INPUT(LINEDESC, 

$DESCRIPTOR('Text: 
NEQ RMSI.EOF 
DO IF NOT .STATUS 

THEN SIGNAL(.STATUS) 

ELSE BEGIN 

STRIUPCASE(LINEDESC.LINEDESC); 


Address of allocated node 
List head of binary tree 
String descriptor for input line 


Zero binary tree head 
Make a dynamic descriptor 


))) 


Read input line 
with this prompt 


IF NOT (STATUS = LIB$INSERT_TREE( 


Report any errors found 


Convert string 
to upper case 


TREEHEAD, 

LINEDESC, 

%REF(1), 
COMPARE.NODE, 
ALLOC.NODE, 
NODE, 

0 )) 

THEN SIGNAL(.STATUS); 


Insert good data into the tree 
Data to insert 
Insert duplicate entries 
Addr. of compare routine 
Addr. of node allocation routine 
Return addr. of 
allocated node here 


END; 
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! End of file encountered. Print the whole tree and exit. 

! - 

IF NOT (STATUS = LIB$TRAVERSE_TREE( 

TREEHEAD, ! Listhead of tree 

PRINT.NODE, ! Action routine to print a node 

0 )) 

THEN SIGNAL(.STATUS); 

RETURN SS$_N0RMAL 

END; ! End of routine tree_start 

ROUTINE ALLOC.NODE (KEYDESC.RETDESC,CONTEXT) = 

BEGIN 
! + 

! This routine allocates virtual memory for a node. 

! 

! INPUTS: 

! 

! KEYDESC 


RETDESC 

CONTEXT 


! OUTPUTS: 

! 

! Memory address returned in longword pointed to by retdesc 

MAP 

KEYDESC : REF BBLOCK, 

RETDESC : REF VECTOR[.LONG]; 

LOCAL 

NODE : REF BBLOCK. 

STATUS; 

STATUS = LIB$GET_VM(*/,REF (NODE$C_LENGTH+ . KEYDESC [DSC$W_LENGTH] ) , NODE) ; 

IF NOT .STATUS 

THEN RETURN .STATUS 
ELSE BEGIN 

NODE[NODE$B_NAMLNG] = .KEYDESC[DSC$W_LENGTH] ; ! Set name length 

CH$MOVE(.KEYDESC[DSC$W_LENGTH], ! Copy in the name 

.KEYDESC[DSC$A_POINTER]. 

NODE[NODE$T_NAME]); 

RETDESC[0] = .NODE; ! Return address to caller 

END; 

RETURN .STATUS 
END; 


Address of string descriptor for key 
(this is the linedesc argument passed 
to LIB$INSERT_TREE) 

Address of location to return address of 
allocated memory 

Address of user context argument passed 
to LIB$INSERT_TREE (not used in this 
example) 
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ROUTINE COMPARE.NODE (KEYDESC,NODE,CONTEXT) = 
BEGIN 
! + 

! This routine compares a key with a node. 

j 

! INPUTS: 

I 

! KEYDESC 


! NODE 

! CONTEXT 

MAP 

KEYDESC : REF BBLOCK, 

NODE : REF BBLOCK; 

RETURN CH$COMPARE(.KEYDESC[DSC$W_LENGTH], ! Compare key with 

! current node 

.KEYDESC[DSC$A_POINTER], 

.NODE[NODE$B_NAMLNG], 

NODE[NODE$T_NAME]) 


Address of string descriptor for new key 
(This is the linedesc argument passed to 
LIB$INSERT_TREE) 

Address of current node 

User context data (Not used in this example) 


END; 

ROUTINE PRINT.NODE (NODE,CONTEXT) * 

BEGIN 
! + 

! This routine is called during the tree traversal. It 
! prints out the left and right subtree pointers, the 
! current node balance, and the name of the node. 

i - 

MAP 

NODE : REF BBLOCK; 

LOCAL 

OUTBUF : BBLOCK[512], 

OUTDESC : BBLOCK[DSC$C_S_BLN], 

STATUS; 

CHIFILL(0,DSC$C_S_BLN,OUTDESC); 

OUTDESC[DSC$W_LENGTH] = 512; 

OUTDESC[DSCIA.POINTER] = OUTBUF; 

IF NOT (STATUS = SYS$FAO($DESCRIPTOR('!XL !XL !XL !XW !AC‘), 

OUTDESC.OUTDESC, 

.NODE,.NODE[NODE$L_LEFT], 

.NODE[NODE$L_RIGHT], 

.NODE[NODE$W_BAL], 

NODE[NODE$B_NAMLNG])) 

THEN SIGNAL(.STATUS) 

ELSE BEGIN 

STATUS = LIB$PUT_OUTPUT(OUTDESC); ! Output the line 

IF NOT .STATUS 

THEN SIGNALS STATUS); 

END; 

RETURN SS$_NORMAL 
END; 

END ! End of module TREE.EXAMPLE 

ELUDOM 


! FAO output buffer 
! Output buffer descriptor 

! Zero descriptor 
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9.8.6 Common I/O Procedures 

LIB$PUT_COMMON allows a program to copy a string into the process's 
common storage area. This area remains defined during multiple image 
activations. LIB$GET_COMMON allows a program to copy a string from the 
common area into a destination string. The programs reading and writing 
the data in the common area must agree upon its amount and format. The 
maximum length of the destination string is defined as follows: 

[min(256, the length of the data in the common storage area) - 4] 

This maximum length is normally 252. 

In BASIC and FORTRAN, you can use these procedures to allow a 
USEROPEN procedure to pass information back to the procedure that 
called it. A USEROPEN procedure cannot write arguments. However, it can 
call LIB$PUT_COMMON to put information into the common area. The 
calling program can then use LIB$GET_COMMON to retrieve it. 

You can also use these procedures to pass information between images run 
successively, such as chained images run by LIB$RUN_PROGRAM. 
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10.1 Image Initialization and Termination 

In most cases, both user and library procedures are written so they are 
self-initializing. This means that they can process information with no special 
action required by the calling program. Initialization is automatic because 
either: 1) the procedure's statically allocated data storage is initialized at 
compile or link time, or 2) a statically allocated flag is tested and set on each 
call so initialization occurs only on the first call. 

Any special initialization—such as a call to other procedures or to system 
services—can be performed on the first call before the main program is 
initialized. For example, you can establish a new environment to alter the 
way errors are handled or messages are printed. 

Such special initialization is required only rarely; however, it need not be 
done by requiring the caller of the procedure to make an explicit initialization 
call. The Run-Time Library provides a system declaration mechanism that 
performs all such initialization calls before the main program is called. 

Special initialization is thus invisible to subsequent callers of the procedure. 

This section describes the system declaration mechanism, including 
LIB$INITIALIZE, which performs calls to any initialization procedure 
declared by the user. This mechanism is available to the Run-Time Library 
so that user procedures that require special initialization can be added to the 
library. However, use of LIB$INITIALIZE is discouraged and should be used 
only when no other method is suitable. 


10.1.1 Image Initialization 

Before the main program or main procedure is called, a number of system 
initialization procedures are called as specified by a 1-, 2-, or 3-longword 
initializaton list set up by the linker. This list consists of the addresses of 
the debugger (if present), the LIB$INITIALIZE procedure (if present), and 
the entry point of the main program or main procedure, in that order. The 
following initialization steps take place: 

1 The image activator maps the user program into the address space of the 
process and sets up useful information such as the program name. Then it 
starts up the command interpreter. 

2 The command interpreter sets up an argument list and calls the next 
procedure in the initialization list (debugger, LIB$INITIALIZE, main 
program, or main procedure). 

3 The debugger, if present, initializes itself and calls the next procedure in 
the initialization list (LIB$INITIALIZE, main program, or main procedure). 

4 LIB$INITIALIZE, if present, is a library procedure that calls each 
library and user initialization procedure declared using the system 
LIB$INITIALIZE mechanism. Then it calls the main program or main 
procedure. 
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5 The main program or main procedure executes, and at the user's 
discretion, accesses its argument list to scan the command or obtain 
information about the image. The main program or main procedure can 
then call other procedures. 

6 Eventually, the main program or main procedure terminates by executing 
a return instruction (RET) with RO set to a standard completion code to 
indicate success or failure, where bit 0 equals 1 for success or 0 for failure. 

7 The completion code is returned to LIB$INITIALIZE (if present), the 
debugger (if present), and finally to the command interpreter, which issues 
a $EXIT system service with the completion status as an argument. Any 
declared exit handlers are called at this point. 

Note: Main programs should not call the $EXIT system service directly. If they 
do, other programs cannot call them as procedures. 

Figure 10-1 illustrates the sequence of calls and returns in a typical image 
initialization. Each box is a procedure activation as represented on the 
image stack. The top of the stack is at the top of the figure. Each upward 
arrow represents the result of a CALLS or CALLG instruction that creates 
a procedure activation on the stack to which control is being transferred. 

Each downward arrow represents the result of a RET (return) instruction. A 
RET instruction removes the procedure activation from the stack and causes 
control to be transferred downward to the next box. 

A user program can alter the image initialization sequence by making a 
PSECT contribution to PSECT LIB$INITIALIZE and declaring EXTERNAL 
LIB$INITIALIZE. This adds the optional initialization steps shown in 
Figure 10-1 labeled "PSECT contribution to LIB$INITIALIZE". (A PSECT is a 
portion of a program with a given protection and set of storage management 
attributes. Program sections that have the same attributes are gathered 
together by the linker to form an image section.) If the initialization 
procedure also performs a coroutine call back to LIB$INITIALIZE, the 
optional steps labeled "Coroutine call back to LIB$INITIALIZE" shown in 
Figure 10-1 are added to the image initialization sequence. 
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Figure 10-1 Sequence of Events during Image Initialization 



ZK-1977-84 


10.1.2 Initialization Argument List 

The following argument list is passed from the command interpreter, the 
debugger, and/or LIB$INITIALIZE to the main program. This argument list 
is the same for each procedure activation. 

(start ,cli-coroutine [,image-inio]) 

The start argument is the address of the entry in the initialization vector that 
is used to perform the call. 

The cli-routine argument is the address of a command interpreter coroutine 
to obtain command arguments. 

The image-info argument is useful image information such as the program 
name. 
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The debugger and/or LIB$INITIALIZE can call the next procedure in the 
initialization chain using the following coding sequence: 


ADDL #4. 4(AP) ; Step to next initialization list entry 

MOVL <D4(AP), RO ; RO = next address to call 

CALLG (AP), (RO) ; Call next initialization procedure 


This coding sequence modifies the contents of an argument list entry. 

Thus, the sequence does not follow the VAX Procedure Calling and 
Condition Handling Standard. However, the argument list can be expanded 
in the future without requiring any change either to the debugger or to 
LIB$INITIALIZE. 


10.1.3 Declaring Initialization Procedures 

Any library or user program module can declare an initialization procedure. 
This procedure will be called when the image is started. The declaration is 
made by making a contribution to PSECT LIB$INITIALIZE, which contains a 
list of procedure entry point addresses to be called before the main program 
or main procedure is called. 

The following MACRO example declares an initialization procedure by 
placing the procedure entry address INIT_PROC in the list: 


.EXTRN LIBIINITIALIZE ; cause library initialization 

; dispatcher to be loaded 

.PSECT LIBIINITIALIZE, NOPIC, USR, CON, REL, GBL, NOSHR, NOEXE, RD, NOWRT, LONG 


.LONG INIT.PROC 
.PSECT ... 


; contribute entry point address of 
; initialization routine. 


The .EXTRN declaration links the initialization procedure dispatcher, 
LIB$INITIALIZE, into your program's image. The reference contains a 
definition of the special global symbol LIB$INITIALIZE, which is the 
procedure entry point address of the dispatcher. The linker stores the value 
of this special global symbol in the initialization list along with the starting 
address of the debugger and main program. The GBL specification ensures 
that the PSECT LIB$INITIALIZE contribution will not be affected by any 
clustering performed by the linker. 


10.1.4 Dispatching to Initialization Procedures 

The LIB$INITIALIZE dispatcher calls each initialization procedure in the list 
with the following argument list. 

CALL init-proc (init-coroutine ,cli-coroutine [, image-info]) 

The init-coroutine argument is the address of a library coroutine to be called 
to effect a coroutine linkage with LIB$INITIALIZE. 

The cli-coroutine is the address of a command interpreter coroutine used to 
obtain command arguments. 

The image-info argument is useful image information such as the program 
name. 
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10.1.5 Initialization Procedure Options 

An initialization procedure has a number of options. It can be used to do the 

following: 

• Set up an exit handler by calling the Declare Exit Handler ($DCLEXH) 
system service, although exit handlers are generally set up by using a 
statically allocated first-time flag. 

• Initialize statically allocated storage, although this is preferably done at 
image activation time using compile-time and link-time data initialization 
declarations, or using a first-time call flag in its statically allocated storage. 

• Call the initialization dispatcher (instead of returning to it) by calling the 
init-coroutine argument. This achieves a coroutine linkage. Control will 
return to the initialization procedure when the main program returns 
control. Then, the initialization procedure should also return control to 
pass back the completion code returned by the main program (to the 
debugger and/or command interpreter). 

• Establish a condition handler in the current frame before performing 
the previous step. This will leave the initialization procedure condition 
handler on the image stack for the duration of the image execution. Since 
this will occur after the command interpreter has set up the catch-all stack 
frame handler, and after the debugger has set up its stack frame handler, 
the initalization procedure handler can override either of these handlers 
since it will receive signals before they do. 


10.1.6 An Example 

The following MACRO code fragment shows how an initialization procedure 
does the following: 

• Establishes a handler 

• Calls the init-coroutine procedure, so that the coroutine calls the 
initialization dispatcher 

• Gets control after the main program returns 

• Returns to the normal exit processing 
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INIT.PROC: 

.WORD ~M<> ; no registers used 

MOVAL HANDLER, (FP) ; establish handler 

... ; perform any other initialization 


10 $: 


CALLG (AP), <DINIT_CO_ROUTINE(AP) 


RET 


continue initialization which 
then calls main program or 
procedure. 

Return here when main program 
returns with R0 * completion 
status return to normal exit 
processing with R0 * completion 
status 


HANDLER: 

.WORD ~M<...> 

MOVL #..., RO 
RET 


condition handler 
register mask 
handle condition 
could unwind to 10$ 

Set completion status with a 
condition value 

resignal or continue depending 
on RO being SS$_RESIGNAL or 
SS$_CONTINUE. 


10.1.7 Image Termination 

Main programs and main procedures terminate by executing a return 
instruction (RET). This returns control to the caller, which may have been 
LIB$INITIALIZE, the debugger, or the command interpreter. The completion 
code, SS$_NORMAL, which has the value 1, should be used to indicate 
normal successful completion. 

Any other condition value can be used to indicate success or failure 
completion. This condition value is used as the parameter to the exit 
($EXIT) system service by the command interpreter. If the severity field 
(STS$V_SEVERITY) is SEVERE or ERROR, the continuation of a batch job or 
command procedure is affected. 

Main programs are discouraged from calling the $EXIT system service 
directly. This allows them to be more like ordinary modular procedures and 
hence usable by other programmers as callable procedures. 
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This section discusses the Run-Time Library procedures that control and 
perform various functions on Digital's DECtalk device. The DECtalk 
procedures are meant solely for use with Digital's DECtalk device. 


11.1 Overview of the DTK$ Facility 

The DECtalk device accepts alphanumeric text from a computer system and 
converts it to human-quality speech. DECtalk speaks this data through its 
internal speaker, an external audio system, or over the telephone. 

The DTK$ Facility consists of procedures that control the functions of the 
DECtalk device. These routines not only control DECtalk's characteristics, 
but also provide functional controls such as reading keys entered on a phone 
keypad or hanging up the phone. In general, the DTK$ procedures supply a 
simple interface between the user and the DECtalk device. 


11.2 Controlling the DECtalk Environment 

I The DTK$ facility supplies several procedures that control the environment in 

which the DECtalk device functions. These procedures are grouped according 
to function and described below. 


11.2.1 Initializing DECtalk 

Before issuing any commands to the DECtalk device, you must first initialize 
it. The procedure DTK$INITIALIZE initializes a DECtalk device and returns 
its associated voice identifier. This procedure also specifies a file specification 
or logical name to which the output associated with the DECtalk device is 
written. 


11.2.2 The DECtalk Device 

Once a DECtalk device has been initialized, you can select various operating 
modes for the device. The DTK$SET_MODE procedure controls how 
DECtalk processes text, according to the modes listed below. Note that it 
is possible to perform a logical OR operation to set more than one mode at a 
time, and any mode that is not specified is reset. 

• DTK$M_SQUARE treats square brackets ([]) as phonemic text delimiters. 
This mode also lets the closing parenthesis character ")" when it appears 
before a word, indicate an alternative pronunciation from the built-in 
dictionary. 

• DTK$M—ASCII uses single-character phonemic translation instead of a 
multiletter translation. This is valid only for the DTC01 device. 

• DTK$M_MINUS pronounces a hyphen (-) as "minus." 
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• DTK$M—EUROPE uses European number format (where a comma 
separates the number from its decimal portion and periods mark off 
digits into groups of 3). This is valid only for the DTC03 device. 

• DTK$M_SPELL spells out all text instead of interpreting the text as words. 
This is valid only for the DTC03 device. 

DTK$SET_MODE can be used to set new modes, to examine the current 
mode settings, or to change the modes and later return them to their previous 
state. 

The DTK$SET_SPEECH_MODE procedure toggles DECtalk's speech on 
and off. In the case of turning the speech off, you can either cause DECtalk 
to stop speaking immediately, or to stop speaking when the current text is 
completed. 

DTK$SET—VOICE controls the actual voice characteristics of the DECtalk 
device. The following is a list of the available voice mode settings for 
DECtalk, along with their voice names and characteristics. 


Voice Mode 

Characteristics 

DTK$K_VOICE_MALE 

Standard male voice 

DTK$K_VOICE_FEMALE 

Standard female voice 

DTK$K_VOICE_CHILD 

Standard child voice 

DTK$K_VOICE_DEER_MALE 

Deep male voice 

DTK$K_VOICE_DEEP_FEMALE 

Deep female voice 

DTK$K_VOICE_OLDER_MALE 

Older male voice 

DTK$K VOICE LIGHT FEMALE 

Light female voice 


The DTK$SET_VOICE procedures also lets you control DECtalk's speech rate, 
as well as the length of the pauses after commas and periods. The speech 
rate of the DECtalk device is measured in words per minute, and the valid 
range is 120 to 350 words per minute. The values that control the comma 
and period pauses are measured in milliseconds. 


11.2.3 The Terminal 


DECtalk I lets you connect a local terminal to the DECtalk device. The DTK$ 
facility supplies two routines that you can use to control the local terminal. 

The DTK$SET_LOGGING_MODE procedure determines the information 
that is displayed on the local terminal connected to the DECtalk device. 

The following is a list of modes that can be set or reset using DTK$ SET- 
LOGGING _MODE. Note that you can perform a logical OR operation to set 
more than one mode at a time, and any mode not specified is reset. 

• DTK$M_TEXT causes all spoken text to be printed on the terminal. 

• DTK$M_PHONEME causes all spoken text to be converted to its 
phonemic equivalent and then printed on the terminal. 

• DTK$M_RAWHOST causes all data received from the host to be 
transmitted, including escape sequences, to the terminal in exactly the 
form in which it is received. 
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• DTK$M—INHOST causes all text received from the host to be printed, 
including escape sequences, on the terminal. However, all control 
characters are first translated to a readable form. 

• DTK$M_OUTHOST causes all characters sent to the host to be printed 
at the terminal. Before printing, control characters are converted to a 
readable form. This readable form is sometimes a mnemonic (for example, 
ESC for escape) and sometimes a letter which has meaning when used 
with the CONTROL key (for example, C for I ctrl/c 1 ). 

• DTK$M —ERROR causes all DECtalk error messages to be printed on the 
terminal. 

• DTK$M_TRACE causes all text received from the host to be printed on 
the terminal, including escape sequences. However, the escape sequences 
are first converted into their symbolic meaning before being printed. 


The procedure DTK$SET_TERMINAL—MODE controls the attributes of the 
local terminal. This procedure can be used to set new modes, to examine the 
current mode settings, or to change the modes and later return them to their 
previous state. All of the following modes are valid. 


DTK$M_HOST 

DTK$M_SPEAK 

DTK$M_EDITED 

DTK$M_HARD 

DTK$M_SETUP 

DTK$M_FILTER 


When set, any characters typed on the local terminal are 
transmitted to the host computer. 

When set, characters typed on the local terminal are 
spoken by DECtalk. (Note that they will be interspersed 
with characters sent from the host.) 

When set, text entered from the local terminal is processed 
one line at a time. 

When set, text is echoed on the local terminal in a manner 
appropriate for hardcopy terminals. When this mode is not 
set, echoing is performed in a manner appropriate for video 
display terminals. 

When set, DECtalk speaks the set-up dialogue. 

When set, DECtalk does not transmit DECtalk-specific 
escape sequences to the local terminal. DECtalk also 
ignores most non-DECtalk escape sequences transmitted 
from the host computer. 


Once again, it is possible to perform a logical OR operation to set more than 
one mode at a time. Any mode that is not specified is automatically reset. 


1.2.4 The Index 


When DECtalk speaks text, the speech rate for the device is much slower 
than the rate of data transmission. This may create a problem if a certain 
task in your program is contingent upon certain speech being complete. The 
DTK$ facility therefore provides you with indexes. An index is a number that 
you insert at an appropriate location in your text. Once DECtalk completes 
speaking all text up to that index, the index value is returned to your program. 
Using this index, your program can then keep track of what text has already 
been spoken. 
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An index could be inserted, for example, following some instructional text 
regarding user input. Once DECtalk speaks the instructional text, it returns 
the index to the program, and this then triggers the program to wait for the 
user's input. You can set an index using the DTK$SET_INDEX procedure. 
The index value must be in the range of 1 to 32767. The DTK$RETURN_ 
LAST-INDEX procedure returns the last index spoken. 


11.2.5 The Dictionary 

DECtalk comes equipped with two dictionaries. The first of these is stored 
in ROM and therefore cannot be changed in any way. A certain amount of 
dynamic storage is allocated for a supplemental dictionary to which you can 
add your own words and pronunciations. 

In order to load a word into this supplemental dictionary, you use the 
DTK$LOAD—DICTIONARY procedure. By specifying both the actual spelling 
of the word and its phonemic definition, you create a new entry in the 
supplemental dictionary. 


11.2.6 Terminating DECtalk 

I In order to deassign the voice identifier that was assigned to the DECtalk 

device when it was initialized, you must call DTK$TERMINATE. This 
procedure terminates all use of the specified DECtalk device by deallocating 
the voice control block and all its substructures. 


11.3 Controlling DECtalk's Speech 

The DTK$ facility provides three different methods for specifying the text that 
DECtalk is to speak. 

DTK$SPEAK_TEXT sends the specified text to the DECtalk device to be 
spoken. You can optionally set one of the following modes: 

• DTK$K_IMMED returns control to the user immediately (this is the 
default). 

• DTK$K_WAIT waits until the text is completely spoken before returning 
control to the user. 

• DTK$K_STATUS waits until the text is completely spoken, and then 
returns a phone status. 

These same modes can be set for DTK$SPEAK_FILE, that speaks the text 
contained in a specified file, and also for DTK$SPEAK—PHONEMIC—TEXT. 
This procedure sends the specified phonemic text to the DECtalk device to be 
spoken. Phonemic text contains the phonemic representations of the words 
to be spoken; that is, the words are spelled as they are pronounced. 


11.4 Controlling DECtalk for Telephone Use 

I One of the most common applications for DECtalk is to serve as an access to 

a remote data base via the telephone. The DTK$ facility therefore supplies 
several routines that improve the interface between DECtalk and the user. 
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11.4.1 The Telephone Keypad 

I The procedure DTK$SET_KEYPAD_MODE enables and disables DECtalk's 

recognition of the telephone keypad. If keypad recognition is enabled with 
auto-stop, DECtalk stops speaking when a terminator is entered. Otherwise, 
disabling keypad recognition takes effect immediately. 


11.4.2 Input Via the Telephone Keypad 

The procedure DTK$READ_KEYSTROKE reads a key entered on the 
telephone keypad, and returns that key's equivalent key code value. These 
key codes are in the form DTK$K_TRM_xxxx, and they are defined in 
DTKDEF. The optional prompt argument lets you specify some text that 
DECtalk speaks before waiting for input. The timeout argument controls the 
number of seconds that DECtalk waits for input. 

DTK$READ_STRING reads a series of keys entered on a telephone keypad 
and returns the key series as a single string. Once again, you can specify 
an optional prompt and a timeout value for this procedure. The optional 
term-code argument returns the key code value of the terminating key 
entered. 


11.4.3 Controlling the Telephone Functions 

In addition to accepting user input, the DTK$ facility also supplies routines 
that control the actual operation of the telephone. 

DTK$ANSWER_PHONE waits for the phone connected to the DECtalk 
device to ring and then answers it. You can specify optional text, that 
DECtalk speaks after answering the phone. The DTK$ facility also supplies 
a procedure for hanging up the phone: DTK$HANGUP_PHONE. This 
procedure speaks an optional message (if specified) and then hangs up the 
phone. DTK$DIAL _PHONE dials the specified number on the telephone. 
You can select either pulse dialing or tone dialing with the mode argument 
for this procedure, and you can also specify how many seconds DECtalk 
should wait for the phone to be answered. The text argument lets you specify 
optional text, that DECtalk speaks once the phone is answered. 
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DTK$ANSWER_PHONE—Wait for Phone 

to Ring and 
Answer 



DTK$ANSWER_PHONE waits for the phone connected to the 
DECtalk device to ring and then answers it. 

FORMAT 

DTK$ANSWER_PHONE voice-id[,num-rings] 

[,text] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

num-rings 

VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Number of rings DECtalk waits for before answering the phone. The optional 
num-rings argument is the address of a signed longword containing this 
number. The default is 1 ring. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text that DECtalk speaks after answering the phone. The optional text 
argument is the address of a descriptor pointing to the text. 

DESCRIPTION 

DTK$ANSWER__PHONE waits for the phone connected to the DECtalk 
device to ring and then answers it. If the num-rings argument is not 
specified, DECtalk answers the phone after 1 ring. After the phone is 
answered, DECtalk speaks any optional text specified. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 


Normal successful completion. 

Any condition value returned by $QIOW. 
Invalid voice-id. 

Wrong number of arguments. 
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DTK$DIAL _PHONE—Dial the Telephone 



DTK$DIAI—PHONE dials the specified number on the telephone. 

FORMAT 

DTK$DIAI_PHONE 

voice-id ,phone-num [,mode] [, text] 

[, timeout] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk machine. The voice-id argument is the 
address of an unsigned longword containing this identifier. The voice 
identifier is returned by the DTK$INITIALIZE routine. 

phone-num 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Phone number to dial. The phone-num argument is the address of a 
descriptor pointing to the specified phone number. 

mode 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode to use when dialing the phone. The optional mode argument is the 
address of a longword bit mask containing this mode. 

The valid modes are: 

DTK$K_DIAI Use pulse dialing. 

PULSE 

DTK$K_DIAI Use tone dialing. 

TONE 

Pulse dialing is the default. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


text 


VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken after the phone is answered, 
address of a descriptor pointing to the specified 


The text argument is the 
text. 


timeout 

VMS Usage: longword-_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Number of seconds to wait for the phone to be answered. The optional 
timeout argument is the address of a signed longword containing this timeout 
value. If omitted, DECtalk dials the phone and then returns control to the 
calling program immediately. 


DTK$DIAL —PHONE dials the specified number on the telephone. If a call is 
currently active, the phone is not hung up. 

Note that this routine does not ensure that the phone is answered; it simply 
dials the specified telephone number. If the user specifies the optional text 
argument, DECtalk speaks this text before returning control to the calling 
program. 

If the timeout argument is specified, the DTC01 device always waits for the 
specified number of seconds before returning control, even if the phone is 
answered before the specified number of seconds has elapsed. On the other 
hand, the DTC03 device interprets the timeout argument as the maximum 
number of seconds to wait before returning control to the calling program. 
That is, the DTC03 device returns control either when the phone is answered 
or when the timeout argument has expired, whichever occurs first. 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_T OOLONG 

DTK$_INVMODE 

DTK$_OFFHOOK 


Normal successful completion. 

Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 

Phone number is too long. 

Invalid mode specified. 

Phone is off hook (phone is already active). 
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Run-Time Library Routines 

DTK$HANGUP_PHONE 


DTK$HANGUP_PHONE—Hang Up the 

Phone 



DTK$HANGUP_PHONE speaks an optional message and then hangs 
up the phone. 

FORMAT 

DTK$HANGUP_PHONE voice-id[,text] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken before hanging up the phone. The optional text argument 
is the address of a descriptor pointing to the specified text. 

DESCRIPTION 

DTK$HANGUP_PHONE hangs up the phone after speaking an optional 
message. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from SQIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 


April 1986 
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Run-Time Library Routines 

DTK$INITIALIZE 


DTK$INITIALIZE—Initialize DECtalk 



DTK$INITIALIZE initializes a DECtalk device and returns the device's 
assigned voice identifier. 

FORMAT 

DTK$INITIALIZE 

new-voice-id, out-device 
[, device-type] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

new-voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Voice identifier of the newly created DECtalk device. The new-voice-id 
argument is the address of an unsigned longword that receives this identifier. 

out-device 

VMS Usage: device—name 
type: character string 

access: read only 

mechanism: by descriptor 

File specification or logical name to which the output associated with the 
DECtalk device is written. The out-device argument is the address of a 
descriptor pointing to this logical name. 

device-type 

VMS Usage: longword—signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Device type of the newly created DECtalk device. The optional device-type 
argument is the address of a signed longword that receives the device-type 
information. The two valid device types are: 

DTK$K_DTC_01 For DECtalk 1. 

DTK$K_DTC_03 For DECtalk III. 

If the device-type information is not received in time, the assigned device¬ 
type is DTK$K_DTC—UNKNOWN. 
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Run-Time Library Routines 

DTK$INITIALIZE 


DESCRIPTION DTK$INITIALIZE creates a DECtalk device and returns its assigned voice 
identifier, new-voice-id. Out-device is the device to which the output 
associated with this newly created DECtalk is written. 

If DTK$INITIALIZE is called to create a second DECtalk on a device that 
already has a voice identifier associated with it, DTK$INITIALIZE simply 
returns the identifier of the already existing DECtalk, along with the condition 
code DTK$_VOIALREXI, which signifies that DECtalk already exists for this 
device. 


CONDITION SS$_NORMAL 

VALUES SS$_xxxx 

RETURNED RMS$_xxxx 

LIB$_xxxx 

LIB$_INSVIRMEM 

DTK$_VOIALREXI 

DTK$_WRONUMARG 


Normal successful completion. 

Any error from SGETDVI. 

Any error from SPARSE. 

Any error from LIB$GET_VM or LIB$GET_EF. 

Insufficient virtual memory to allocate needed 
buffer. 

DECtalk already exists for this device. 

Wrong number of arguments. 


April 1986 
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Run-Time Library Routines 

DTK$LOAD_DICTIONARY 


DTK$LOAD_DICTIONARY 

Load a Word into the DECtalk Dictionary 



DTK$LOAD_DICTIONARY loads a phonemic definition of a word 
into the DECtalk dictionary. 

FORMAT 

DTK$LOAD_DICTIONARY voice-id,text 

,substitution 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Word to be loaded into the DECtalk dictionary. The text argument is the 
address of a descriptor pointing to the specified word. 

substitution 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Phonemic definition of the word specified by the text argument. The 
substitution argument is the address of a descriptor pointing to the phonemic 
representation of the specified word. 


DESCRIPTION DTK$LOAD_DICTIONARY loads the phonemic definition of a specified 
word into the DECtalk dictionary. 
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Run-Time Library Routines 

DTK$LOAD_DICTIONARY 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOIID 

DTK$_NOROOM 

DTK$_DEFT OOLON 


Normal successful completion. 

Wrong number of arguments. 

Invalid voice-id. 

No room in the dictionary to add the specified 
word. 

Word definition is too long. 


April 1986 
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DTK$READ_KEYSTROKE 


DTK$READ—KEYSTROKE—Read a Key 

Entered on the 
Keypad 

DTK$READ_KEYSTROKE reads a key entered on the phone keypad. 


FORMAT 

DTK$READ_KEYSTROKE 

voice-id,key-code 
[, prompt] [, timeout] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

voice-id 



VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

key-code 

VMS Usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

The DTK$K_TRM_xxxx code for the key entered on the keypad. The key- 
code argument is the address of a signed longword that receives this code. 
The valid codes are listed in DTKDEF. 


prompt 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Text to be spoken before waiting for input. The optional prompt argument is 
the address of a descriptor pointing to this text. 
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Run-Time Library Routines 

DTK$READ_KEYSTROKE 


timeout 


VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Number of seconds to wait for input. The optional timeout argument is the 
address of a signed longword containing the specified number of seconds 
the DECtalk device waits for input. If the timeout argument is omitted, 
DTK$READ_KEYSTROKE waits for input indefinitely. 


DESCRIPTION DTK$READ_KEYSTROKE reads a key entered on the phone keypad. If the 

optional text argument is specified, DECtalk speaks this text before waiting 
for input. If the keypad mode has not yet been set, this routine will set the 
phone keypad to auto-stop mode. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SSS—Xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_ONHOOK 

DTK$_WINK 


Normal successful completion. 
Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 
Phone is on hook (inactive). 

A wink has occurred. 


April 1986 
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DTK$READ_STRING 


DTK$READ_STRING 

Read a Series of Keys Entered on the 
Keypad 


DTK$READ_STRING reads a series of keys entered on the phone 
keypad. 

FORMAT 

DTK$READ_STRING 

voice-id, out-string [, prompt] 

[, timeout] [, term-code] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


out-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which the keys being read are written. The out-string argument 
is the address of a descriptor pointing to this string. 


prompt 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken before waiting for input. The optional prompt argument is 
the address of a descriptor pointing to this text. 


timeout 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 
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Run-Time Library Routines 

DTK$READ_STRING 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


mechanism: by reference 

Number of seconds DECtalk waits for input. The optional timeout argument 
is the address of a signed longword containing the number of seconds 
DECtalk waits for input. If the timeout argument is omitted, DTK$READ— 
STRING waits for input indefinitely. 


term-code 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword (signed) 
write only 
by reference 


The DTK$K_TRM—xxxx code for terminating key entered. The optional 
term-code argument is the address of a signed longword that receives this 
code. The valid codes are located in DTKDEF. 


DTK$READ—STRING reads a series of keys entered on the phone keypad 
and stores them in out-string. If the optional prompt argument is specified, 
DECtalk speaks the specified text before waiting for input. The valid 
terminators are the number sign (#) and asterisk (*). If the keypad mode 
has not yet been set, this routine will set the phone keypad to auto-stop 
mode. 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_ONHOOK 

DTK$_WINK 


Normal successful completion. 
Any error from $QIOW. 

Invalid voice-id. 

Wrong number of arguments. 
Phone is on hook (inactive). 

A wink has occurred. 
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Run-Time Library Routines 

DTK$RETURN_LAST_INDEX 


DTK$RETURN—LAST—INDEX—Return 

Last Index 
Spoken 



DTK$RETURN_LAST_INDEX returns the last index spoken. 

FORMAT 

DTK$RETURN_LAST_INDEX voice-id,p-index 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

p-index 

VMS Usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Index to be returned. The p-index argument is the address of a signed 
longword that receives the index identifier. 

DESCRIPTION 

DTK$RETURN_LAST_INDEX returns the last index spoken. An index is 
inserted into the output stream with the DTK$SET_INDEX routine. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 
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DTK$SET_INDEX 


DTK$SET_ 

-INDEX—Insert an Index at the 
Current Position 

DTK$SET_INDEX inserts an index into the current output stream. 

FORMAT 

DTK$SET_I N DEX voice-id ,p-index 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

p-index 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Index to be inserted. The p-index argument is the address of a signed 
longword containing the index value. Valid values are in the range of 1 to 
32767. An index of zero is reserved for use by DIGITAL. 

DESCRIPTION 

DTKSSET—INDEX inserts an index into the current position in the output 
stream. Allowable values for p-index are in the range of 1 to 32767. An 
index of zero is reserved for use by DIGITAL. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Normal successful completion. 

SS$_xxxx Any error from $QIOW. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_WRONUMARG Wrong number of arguments. 

DTK$_INVARG Invalid argument. 
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DTK$SET_KEYPAD_MODE 


DTK$SET_ 

-KEYPAD-MODE—Turn the 

Phone 

Keypad On 
and Off 

DTK$SET_KEYPAD_MODE turns recognition of the telephone 
keypad on or off. 

FORMAT 

DTK$SET_KEYPAD_MODE voice-id,mode 

RETURNS 

VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode that determines the status of the telephone keypad. The mode 
argument is the address of a longword bit mask containing this mode. The 
valid mode specifiers are: 

DTK$K_KEYPAD_ON Turns the keypad on. 

DTK$K_KEYPAD_OFF Turns the keypad off. 

DTK$K_KEYPAD_AUTO Turns the keypad on with autostop. 


DESCRIPTION DTK$SET_KEYPAD_MODE turns the recognition of the telephone keypad 
on or off. Depending upon the mode specified, the keypad can be turned on, 
off, or on with auto stop. Auto stop mode means that DECtalk stops speaking 
when a terminator is entered. 
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Run-Time Library Routines 

DTK$SET_KEYPAD_MODE 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Normal successful completion. 

DTK$_WRONUMARG Wrong number of arguments. 

DTK$_INVVOIID Invalid voice-id. 

DTK$_ONHOOK Phone is on hook (inactive). 

DTK$_INVMODE Invalid mode specified. 

DTK$_WINK A wink has occurred. 


April 1986 
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DTK$SET_LOGGING_MODE 


DTK$SET_LOGGING_MODE 

Set the Logging Mode for the Video 

Terminal Connected to the DECtalk Device 


DTK$SET_LOGGING_MODE controls the information that is 
displayed on the video terminal while the DECtalk device is 
functioning. 


FORMAT 

DTK$SET_LOGGING_MODE 

voice-id [,ne w-mode] 




[, old-mode] 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 



access: 

write only 



mechanism: 

by value 



ARGUMENTS 


voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


new-mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 

• DTK$M_TEXT 

• DTK$M_PHONEME 

• DTK$M _R AWHOST 

• DTK$M _INHOST 

• DTK$M —OUTHOST 

• DTK$M_ERROR 

• DTK$M_TRACE 

• DTK$M_DEBUG 
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Run-Time Library Routines 

DTK$SET_LOGGING_MODE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


It is possible to logically OR the bits in the bit mask together to set more than 
one mode at a time. Any mode not specified is reset. 


old-mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DTK$SET_LOGGING_MODE sets or resets the specified modes on the 
DECtalk device. It controls the information that is displayed on a video 
terminal connected to the DECtalk device. Note that any modes not explicitly 
set are reset by DTK$SET_LOGGING_MODE. 

DTK$SET_LOGGING—MODE has two optional parameters, new-mode and 
old-mode. By specifying different combinations of these arguments. You can 
use DTK$SET_LOGGING—MODE in various ways. 

• To use DTK$SET_LOGGING_MODE to determine the current mode 
settings, use the following format: 

DTK$SET_LOGGING_MODE (voice.id ,.old.mode) 

• To use DTK$SET_LOGGING_MODE to set the bits without regard to 
their current setting, use the following format: 

DTK$SET_LOGGING_MODE (voice.id .new.mode) 

• To use DTK$SET—LOGGING—MODE to save the current settings, set new 
modes, and later restore the original settings, use the following format: 

DTK$SET_LOGGING_MODE (voice.id ,new.mode ,save_old_settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following format: 

DTK$SET_LOGGING_MODE (voice-id .save.old.settings) 

This sets the new mode settings according to those previously retrieved. 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOID 

DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Invalid mode specified. 
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DTK$SET_MODE 


DTK$SET_MODE 

Set the Mode for the DECtalk Terminal 



DTK$SET_MODE sets or resets the mode settings of the DECtalk 
terminal. 

FORMAT 

DTK$SET_MODE voice-id [,new-mode] [, old-mode] 

RETURNS 

VMS Usage: cond—value 
type: long word (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

new-mode 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 

• DTK$M_SQUARE 

• DTK$M—ASCII (valid for the DTC01 device only) 

• DTK$M_MINUS 

• DTK$M-EUROPE (valid for the DTC03 device only) 

• DTK$M-SPELL (valid for the DTC03 device only) 

It is possible to logically OR the bits in the bit mask together to set more 
than one mode at a time. Any mode not specified is reset. If the new-mode 
argument is omitted, the current mode is unchanged. 
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Run-Time Library Routines 

DTK$SET_MODE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


old-mode 


VMS Usage: mask_longword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DTK$SET_MODE controls the mode settings for the DECtalk device. Note 
that any modes not explicitly set are reset by DTK$SET_MODE. 

DTK$SET_MODE has two optional parameters, new-mode and old-mode. 
By specifying different combinations of these arguments, DTK$SET_MODE 
can be used in various ways. 

• To use DTK$SET_MODE to determine the current mode settings, use the 
following format: 

DTK$SET_MODE (voice.id t ,old_mode) 

• To use DTK$SET_MODE to set the bits without regard to their current 
setting, use the following format: 

DTK$SET_MODE (voice.id ,new_mode) 

• To use DTK$SET-MODE to save the current settings, set new modes, and 
later restore the original settings, use the following format: 

DTK$SET_MODE (voice_id ,new_mode .save_old_settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following format: 

DTK$SET_MODE (voice-id .save_old_settings) 

This sets the new mode setting according to those previously retrieved. 


SS$_NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOID 

DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Invalid mode specified. 
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DTK$SET_SPEECH_MODE 


DTK$SET_ 

-SPEECH_MODE—Turn Speech 

Mode On and 
Off 

DTK$SET_SPEECH_MODE either starts or stops the DECtalk 
device's speech. 

FORMAT 

DTK$SET_SPEECH_MODE voice-id ,new-mode 

[, old-mode] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

new-mode 

VMS Usage: mask-Jongword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode to be set. The new-mode argument is the address of a longword bit 
mask containing the specified mode. Valid values are: 

DTK$K_SPEAK Start speaking. 

DTK$K_STOP Stop speaking when current text is completed. 

DTK$K_HALT Stop speaking immediately. 

If the new-mode argument is omitted, the current mode is unchanged. 

old-mode 

VMS Usage: mask-Jongword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Current speech mode of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
mode setting before enabling the new mode. The values returned in old¬ 
mode are the same as those valid for the new-mode argument. 
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DTK$SET_SPEECH_MODE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


DTK$SET_SPEECH_MODE starts or stops the speech of the DECtalk 
device. In the case of stopping DECtalk's speech, the user can either stop 
the DECtalk device immediately or stop it after it has finished speaking. 
Because DTK$SET_SPEECH_MODE is used to set a new speech mode, the 
new-mode argument is required. 


SSS—NORMAL 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 


Normal successful completion. 
Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 
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DTK$SET_TERMINAI_MODE 


DTK$SET_TERM IIMAL _MODE 

Set the Mode for the Video Terminal 

Connected to the DECtalk Device 



DTK$SET_TERMINAL_MODE controls the attributes of the video 
terminal connected to the DECtalk device. 

FORMAT 

DTK$SET_TERMINAI_MODE voice-id 

[,new-mode] 

[,old-mode] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

new-mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

DECtalk mode to be set. The optional new-mode argument is the address 
of a longword bit mask containing the specified mode. Valid values for 
new-mode are: 

• DTK$M_HOST 

• DTK$M—SPEAK 

• DTK$M_EDITED 

• DTK$M —HARD 

• DTK$M_SETUP 

• DTK$M-FILTER 

It is possible to OR these values together to set more than one mode at a 
time. Any mode not specified is reset. If the new-mode argument is omitted, 
the current mode is unchanged. 
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DTK$SET_TERMINAI_MODE 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


old-mode 


VMS Usage: mask-Jongword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Current mode settings of the DECtalk device. The optional old-mode 
argument is the address of a longword bit mask that receives the current 
DECtalk settings. 


DTK$SET_TERMINAL_MODE controls the mode settings for the video 
terminal connected to the DECtalk device. Note that any modes not explicitly 
set are reset by DTK$SET_TERMINAL_MODE. 

DTK$SET_TERMINAL—MODE has two optional parameters, new-mode 
and old-mode. By specifying different combinations of these arguments, 
DTK$SET_TERMINAL—MODE can be used in various ways. 

• To use DTK$SET-TERMINAL __MODE to determine the current mode 
settings, use the following format: 

DTK$SET_TERMINAL_MODE (voice.id ,,old_mode) 

• To use DTK$SET_TERMINAL—MODE to set the bits without regard to 
their current setting, use the following format: 

DTK$SET__TERMINAL_MODE (voice.id ,new_mode) 

• To use DTK$SET_TERMINAL—MODE to save the current settings, set 
new modes, and later restore the current settings, use the following 
format: 

DTK$SET_TERMINAL_MODE (voice_id ,new_mode ,save_old_settings) 

This retrieves the current bit settings and then sets the mode according to 
the new-mode argument. 

Later, to restore the mode to its former state, specify the following format: 

DTK$SET_TERMINAL_MODE (voice-id ,save.old.settings) 

This sets the new mode settings according to those previously retrieved. 


SSS—NORMAL 

DTK$_WRONUMARG 

DTK$_INVVOID 

DTK$_INVMODE 


Normal successful completion. 
Wrong number of arguments. 
Invalid voice-id. 

Invalid mode specified. 
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DTK$SET_VOICE 


DTK$SET_VOICE—Set Voice 

Characteristics 


DTK$SET_VOICE changes the DECtalk voice characteristics to 
match those specified. 

FORMAT 

DTK$SET_VOICE 

voice-id [, new-voice] [,speech-rate] 

[, comma-pause] [, period-pause] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


new-voice 

VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Type of voice. The optional new-voice argument is the address of a signed 
longword containing any valid new-voice value. Valid values for new-voice 
are: 


DTK$K_VOICE_MALE 

DTK$K_VOICE_FEMALE 

DTK$K_VOICE_CHILD 

DTK$K_VOICE_DEEP_MALE 

DTK$K_VOICE_DEEP_FEMALE 

DTK$K_VOICE_OLDER_MALE 

DTK$K_VOICE_LIGHT_FEMALE 


Standard male voice 
Standard female voice 
Standard child voice 
Deep male voice 
Deep female voice 
Older male voice 
Light female voice 
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DTK$SET_VOICE 


speech-rate 

VMS Usage: longword—signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Rate at which DECtalk speaks, measured in words per minute. The optional 
speech-rate argument is the address of a signed longword containing this 
rate. The valid range of values for speech-rate is 120 to 350 words per 
minute. 

comma-pause 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of milliseconds by which to increase the time DECtalk pauses after 
a comma. The optional comma-pause argument is the address of a signed 
longword containing this number. A value of zero resets the pause time to 
the hardware default value. 


period-pause 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of milliseconds by which to increase the time DECtalk pauses after 
a period. The optional period-pause argument is the address of a signed 
longword containing this number. A value of zero resets the pause time to 
the hardware default value. 


DESCRIPTION DTK$SET_VOICE changes the DECtalk voice characteristics to match those 
specified. DTK$SET_VOICE can change the voice type, the rate of speech, 
and the number of milliseconds DECtalk pauses after commas and periods. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SSS—Xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVARG 

OTS$_xxxx 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid argument. 

Any error from OTS$CVT_l_TU. 


April 1986 


RTL-2.25 















Run-Time Library Routines 

DTK$SPEAK_FILE 


DTK$SPEAK_FILE—Speak the Text in a 



Specified File 

DTK$SPEAK_FILE speaks the text contained in the specified file. 

FORMAT 

DTK$SPEAK_FILE voice-id,filespec [,mode] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification of the file containing the text to be spoken. The filespec 
argument is the address of a descriptor pointing to this file. 

mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode characteristic. The optional mode argument is the address of a 
longword bit mask containing the specified mode. Valid values for the 
mode argument are: 

DTK$K_IMMED Return to the user immediately (default). 

DTK$K_WAIT Wait until the text is completely spoken. 

DTK$K_STATUS Wait until the text is completely spoken, and then 

return a phone status. 

DESCRIPTION 

DTK$SPEAK_FILE speaks the text contained in the specified file. 
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DTK$SPEAK_FILE 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

RMS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 


Normal successful completion. 
Any error from $QIO. 

Any error generated by RMS. 
Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 
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DTK$SPEAK_PHON EM IC—TEXT 


DTK$SPEAK_PHONEMIC_TEXT 
Speak the Specified Phonemic Text 

DTK$SPEAK_PHONEMIC_TEXT sends the specified phonemic text 
to the DECtalk device to be spoken. 


FORMAT 

DTK$SPEAK_PHONEMIC_TEXT 

voice-id,text 
[,mode] 

RETURNS 

VMS Usage: 

cond_value 



type: 

longword (unsigned) 



access: 

write only 



mechanism: 

by value 


ARGUMENTS 

voice-id 




VMS Usage: 

identifier 



type: 

longword (unsigned) 



access: 

read only 



mechanism: 

by reference 



Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 


text 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Phonemic text to be spoken. The text argument is the address of a descriptor 
pointing to the specified phonemic representation of the text. 


mode 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode characteristic. The optional mode argument is the address of a 
longword bit mask containing the specified mode. Valid values for the 
mode argument are: 


DTK$K_IMMED 
DTK$K_WAIT 
DTK$K_ST ATUS 


Return to the user immediately (default). 

Wait until the text is completely spoken. 

Wait until the text is completely spoken, and then 
return a phone status. 


DESCRIPTION DTK$SPEAK_PHONEMIC_TEXT sends the specified phonemic 

representation of some text to the DECtalk device. This text contains the 
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DTK$SPEAK_PHONEMIC_TEXT 


CONDITION 

VALUES 

RETURNED 


phonetic representations of the words to be spoken; that is, the words are 
spelled as they are pronounced. The DECtalk device then speaks this text. 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 

DTK$_ONHOOK 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 

Phone is on hook (inactive). 
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DTK$SPEAK_TEXT 


DTK$SPEAK—TEXT—Speak the Specified 

Text 



DTK$SPEAK_TEXT sends the specified text to the DECtalk device 
to be spoken. 

FORMAT 

DTK$SPEAK_TEXT voice-id,text[,mode] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text to be spoken. The text argument is the address of a descriptor pointing 
to the specified text. 

mode 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Mode characteristic. The optional mode argument is the address of a 
longword bit mask containing the specified mode. Valid values for the 
mode argument are: 

DTK$K_JMMED Return to the user immediately (default). 

DTK$K_WAIT Wait until the text is completely spoken. 

DTK$K_STATUS Wait until the text is completely spoken, and then 

return a phone status. 

DESCRIPTION 

DTK$SPEAK_TEXT sends the specified text to the DECtalk device. The 
DECtalk device then speaks this text. 
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DTK$SPEAK_TEXT 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_xxxx 

DTK$_INVVOIID 

DTK$_WRONUMARG 

DTK$_INVMODE 

DTK$_ONHOOK 


Normal successful completion. 
Any error from $QIO. 

Invalid voice-id. 

Wrong number of arguments. 
Invalid mode specified. 

Phone is on hook (inactive). 
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DTK$TERMINATE 


DTK$TERMINATE—Terminate DECtalk 



DTK$TERMINATE terminates the use of an initialized DECtalk. 

FORMAT 

DTKSTERMINATE voice-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

voice-id 

VMS Usage: identifier 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Voice identifier of the DECtalk device. The voice-id argument is the address 
of an unsigned longword containing this identifier. The voice identifier is 
returned by the DTK$INITIALIZE routine. 

DESCRIPTION 

DTK$TERMINATE terminates the use of the specified DECtalk device. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

SS$_xxxx Any error from $DASSGN. 

LIB$_xxxx Any error from LIB$FREE_VM or LIB$FREE_EF. 

DTK$_WRONUMARG Wrong number of arguments. 
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LIB$ADDX 


LIB$ADDX—Add Two Multiple-Precision 
Binary Numbers 


LIB$ADDX adds two signed two's complement integers of arbitrary 
length. 

FORMAT 

LIB$ADDX a ,b,result [Jen] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


a 

VMS Usage: longword_signed 

type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

First multiple-precision, signed two's complement integer which LIB$ADDX 
adds to the second two's complement integer. The a argument is the address 
of the array containing the two's complement number to be added. 


b 

VMS Usage: longword_signed 

type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

Second multiple-precision, signed two's complement integer, which 
LIB$ADDX adds to the first two's complement integer. The b argument 
is the address of the array containing the two's complement number. 


result 

VMS Usage: longword_signed 

type: longword integer (signed) 

access: write only 

mechanism: by reference, array reference 

Multiple-precision, signed two's complement integer result of the addition. 
The result argument is the address of the array into which LIB$ADDX writes 
the result of the addition. 


len 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Length in longwords of the arrays to be operated on; each array is of length 
len. The len argument is the address of a signed longword integer containing 
the length. Len must not be negative. This is an optional argument. If 
omitted, the default is 2. 
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LIB$ADDX 


DESCRIPTION LIB$ADDX adds two signed two's complement integers of arbitrary length. 

The integers are located in arrays of longwords. The higher addresses of these 
longwords contain the higher-precision parts of the values. The highest- 
addressed longword contains the sign and 31 bits of precision. The remaining 
longwords contain 32 bits of precision in each. The number of longwords in 
each array is specified in the optional argument, len. The default length is 
two, which corresponds to the VAX quadword data type. 

Any two or all three of the first three arguments can be the same. 


CONDITION 

SS$_NORMAL 

Routine successfully completed. 

VALUES 

SS$_INTOVF 

Integer overflow. The result is correct, except that 

RETURNED 


the sign bit is lost. 


EXAMPLE 


O 

C This FORTRAN example program illustrates the use 
C of LIBIADDX. 

C- 


INTEGER A(2),B(2),C(2).RETURN 
DATA A/•00000001•x.•7FFF407F 1 x/ 
DATA B/ 1 FFFFFFFF•x.•8000BF80'x/ 


O 

C The highest addressed longword of "A" is A(2). 

C So, "A” represents the integer value ('7FFF407F'x) * 16**7 + 1. 

C That is. A(2) is 576447592255193089. 

C "B" is the twos complement representation ot "-A". 

C- 

RETURN - LIB$ADDX(A,B,C) 

TYPE *,'Let A - 576447592255193089.' 

TYPE *,'Then A + B is 0.' 

TYPE 1,0(2),C(l) 

1 FORMAT(' "A" - "A" is *,1H'.II.II,3H'x.) 

TYPE *,'Note that C is C(2) concatenated with C(l).' 

C+ 

C Let "A" have the value 72057594037927937 = '1000000000000001'x. 

C Let "B" have the value 4294967295 = '00000000FFFFFFFF'x. 

C- 

A(l) - '00000001'x 
A(2) = '10000000'x 
B(l) = 'FFFFFFFF'x 
B(2) = '00000000'x 
C+ 

C Then "A" ♦ "B" is 72057598332895232. 

C- 

RETURN « LIB$ADDX(A,B,C) 

TYPE *.' ' 

TYPE *,'LET A = 72057594037927937 and B - 4294967295' 

TYPE *,'Then A + B is ',C 
TYPE 2,C(2),C(1) 

2 FORMAT (' 72057598332895232 is represented as ',1H',Z8,Z8,3H'x.) 
TYPE *,'Recall that 72057598332895232 is C(2) concatenated 

1 with C(l).' 

END 
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This FORTRAN example demonstrates how to call LIB$ADDX. The output 
generated by this program is as follows: 

Let A = 576447592255193089. 

Then A + B is 0. 

"A" - "A" is '00'x. 

Note that C is C(2) concatenated with C(l). 

LET A * 72057594037927937 and B = 4294967295 
Then A + B is 0 268435457 

72057598332895232 is represented as '10000001 0'x. 

Recall that 72057598332895232 is C(2) concatenated with C(l). 
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LIB$ANALYZE_SDESC—Analyze String 



Descriptors 

LIB$ANALYZE_SDESC extracts the length and the address at which 
the data starts for a variety of string descriptor classes. 

FORMAT 

LIB$ANALYZE_SDESC inp-dsc Jen ,data-adr 

corresponding 
jsb entry point: 

LIB$ANALYZE_SDESC_R2 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

inp-dsc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Input descriptor from which LIB$ANALYZE_DESC extracts the data's length 
and starting address. The inp-dsc argument is the address of a descriptor 
pointing to this descriptor. 

len 

VMS Usage: word—unsigned 
type. word (unsigned) 

access: write only 

mechanism: by reference 

Length of the data; LIB$ANALYSE_DESC extracts this length value from 
the input descriptor. The len argument is the address of an unsigned word 
integer into which LIB$ANALYZE_SDESC writes the length. 

data-adr 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Starting address of the data; LIB$ANALYZE_DESC extracts this address from 
the input descriptor. The data-adr argument is the address of an unsigned 
longword into which LIB$ANALYZE_DESC writes the starting address of the 
data. 
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LIB$ANALYZE_SDESC 


DESCRIPTION LIB$ANALYZE_SDESC extracts the length and the address at which the data 

starts for a variety of string descriptor classes. Following is a description of 
the classes of string descriptors. 


Class 

Description 

Restrictions/Notes 

A 

Array 

DSC$I_ARSIZE must be less than 65536 

bytes. 

D 

Decimal string 

None. 

NCA 

Noncontiguous array 

Same as Class A. 

S 

Scalar, string 

None. 

SD 

Decimal scalar 

DSC$B_DIGITS and DSC$B_SCALE are 
ignored by LIB$CVT_DX_DX; however, 
users should fill these fields with valid 
values. Zero is allowed. 

VS 

Varying string 

Length returned is CURLEN. 

Z 

Unspecified 

Treated as Class S. 


See STR$ANALYZE_SDESC for a similar procedure that signals an error 
rather than returning a status. 


CONDITION SS$_NORMAL 
VALUES LIB$_INVSTRDES 

RETURNED 


Routine successfully completed. 

Invalid string descriptor. An array descriptor has an 
ARSIZE greater than 65,535 bytes, or the class is 
unsupported. 
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LIB$ASI\I_WTH_MBX 


LIB$ASN_WTH—MBX—Assign Channel 

with Mailbox 

LIB$ASN_WTH_MBX assigns a channel to a specified device and 
associates a mailbox with the device. It returns both the device 
channel and the mailbox channel. 


FORMAT 

LIB$ASN 

_WTH_M BX dev-nam,max-msg, buf-quo 
,dev-chn ,mbx-chn 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

read only 


mechanism: 

by value 

ARGUMENTS 

dev-nam 



VMS Usage: 

device—name 


type: 

character string 


access: 

read only 


mechanism: 

by descriptor 


Device name which LIB$ASN_WTH_MBX passes to the $ASSIGN service. 
The dev-nam argument is the address of a descriptor pointing to the device 
name. 


max-msg 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Maximum message size that can be sent to the mailbox; LIB$ASN_WTH_ 
MBX passes this argument to the $CREMBX service. The max-msg argument 
is the address of a signed longword integer containing this maximum message 
size. 


buf-quo 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword integer (signed) 
read only 
by reference 


Number of system dynamic memory bytes that can be used to buffer 
messages sent to the mailbox; LIB$ASN_ WTH_MBX passes this argument 
to the $CREMBX service. The buf-quo argument is the address of a signed 
longword integer containing this buffer quota. 
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dev-chn 

VMS Usage: worcL_signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Device channel which LIB$ASN_WTH_MBS receives from the $ASSIGN 
service. The dev_chn argument is the address of a signed word integer into 
which $ASSIGN writes the device channel. 


mbx-chn 

VMS Usage: channel 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Mailbox channel which LIB$ASN_WTH_MBX receives from the $CREMBX 
service. The mbx_chn argument is the address of a signed word integer into 
which $CREMBX writes the mailbox channel. 


DESCRIPTION A mailbox is a virtual device used for communication between processes. 

A channel is the communication path that a process uses to perform I/O 
operations to a particular device. LIB$ASN_WTH_MBX assigns a channel to 
a device and associates a mailbox with the device. It returns both the device 
channel and the mailbox channel to the mailbox. 

Normally, a process calls the $CREMBX system service to create a mailbox 
and assign a channel and logical name to it. Any process running in the same 
group and using the same logical name uses the same mailbox. 

Sometimes this is not desirable. For example, when a program connects 
explicitly with another process across a network, the program uses a mailbox 
to obtain the data confirming the connection and to store the asynchronous 
messages from the other process. If that mailbox is shared with other 
processes in the same group, there is no way to determine which messages 
are intended for which processes; the processes will read each other's 
messages, and the original program will not receive the correct information 
from the cooperating process across the network link. 

LIB$ASN_WTH__MBX avoids this situation by associating the physical 
mailbox name with the channel assigned to the device. To create a temporary 
mailbox for itself and other processes cooperating with it, your program calls 
LIB$ASN_WTH_MBX. The Run-Time Library procedure assigns the channel 
and creates the temporary mailbox by using the system services $GETCHN, 
$ASSIGN, and $CREMBX. Instead of a logical name, the mailbox is identified 
by a physical device name of the form MBcu. The physical device name 
MBcu is made up of the following elements: 

MB Indicates that the device is a mailbox 
c Is the controller 

u Is the unit number 

The procedure returns this device name to the calling program, which 
then must pass the mailbox channel to the other program(s) with which it 
cooperates. In this way, the cooperating processes access the mailbox by its 
physical name, instead of by its group-wide logical name. 
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The calling program passes the procedure a device name, which specifies 
the device to which the channel is to be assigned. For this argument (called 
dev-nam), you may use a logical name. If you do so, the procedure attempts 
one level of logical name translation. 

The privilege restrictions and process quotas required for using this procedure 
are those required by the $GETCHN, $CREMBX, and $ ASSIGN system 


services. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 


Any condition value returned by the called system services $ASSIGN, 
$CREMBX, $GETCHN, and $FAO. 


Routine successfully completed. 
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LIB$AST_IN—PROG—AST in Progress 



LIB$AST_IN_PROG indicates whether an AST is currently in 
progress. 

FORMAT 

LI B$AST_I N_PROG 

RETURNS 

VMS Usage: boolean 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Truth value that indicates whether an AST is currently in progress (value=l) 
or not (value=0). 

ARGUMENTS 

None. 

DESCRIPTION 

An asynchronous system trap (AST) is a VAX/VMS mechanism for providing 
a software interrupt when an external event occurs, such as the user typing 
CTRL/C. When an external event occurs, VAX/VMS interrupts the execution 
of the current process and calls a procedure that you supply. While that 
procedure is active, the AST is said to be in progress, and the process is said 
to be executing at AST level. When your AST procedure returns control to 
the original process, the AST is no longer active and execution continues 
where it left off. 

LIB$AST_IN_PROG indicates to the calling program whether an AST 
is currently in progress. Your program can call LIB$AST_IN_PROG to 
determine whether it is executing at AST level, and then take appropriate 
action. This procedure is useful if you are writing AST-reentrant code, which 
takes different actions depending on whether an AST is in progress. For 
example, the procedure might have two separate statically allocated storage 
areas, one for AST level and one for non-AST level. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


PROGRAM AST.IN.PROGRESS(INPUT, OUTPUT); 
FUNCTION LIB$AST_IN_PROG : INTEGER; EXTERN; 

VAR 

ASTVALUE : INTEGER; 

BEGIN 

ASTVALUE := LIB$AST_IN_PROG; 

CASE ASTVALUE OF 

0 : WRITELN('AN AST IS NOT IN PROGRESS'); 

1 : WRITELN('AN AST IS IN PROGRESS'); 

END { of the case statement > 

END. 


This PASCAL program determines whether or not an AST is in progress. 
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LIB$ATTACH—Attach Terminal to Process 

LIB$ATTACH requests the calling process's Command Language 



Interpreter (CLI) to detach the terminal of the calling process and to 
reattach it to a different process. 

FORMAT 

LI B$ ATT AC H process-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

process-id 

VMS Usage: process-id 
type: longword integer (unsigned) 

access: read only 

mechanism: by reference 

Identification of the process to which LIB$ATTACH requests the calling 
process to attach its terminal. The process-id argument is the address of an 
unsigned longword integer containing the process identification. The specified 
process must be currently detached (by means of a SPAWN or ATTACH 
command, or by a call to LIB$SPAWN or LIB$ATTACH) and must be part of 
the caller's job. 

DESCRIPTION 

LIB$ATTACH requests the calling process's Command Language Interpreter 
(CLI) to detach the terminal of the calling process and to reattach it to 
a different process. The calling process then hibernates. LIB$ATTACH 
provides the same function as the DCL command ATTACH. For more 
information, see the VAX/VMS DCL Dictionary. 

LIB$ATTACH is supported for use with the DCL CLI. If used with the 

Monitor Control Routine (MCR) CLI, the error status LIB$_NOCLI will be 
returned. If an image is run directly as a subprocess or as a detached process, 
there is no CLI present to perform this function. In such cases the error status 
LIB$_NOCLI is returned. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SS$_NONEXPR 

LIB$_ATTREQREF 

LIB$_NOCLI 


LIB$_UNECLIERR 


Procedure successfully completed. 

Nonexistent process. The process specified by 
process-id does not exist. 

Attach request refused. The specified process 
could not be attached to. Either it was not 
detached or did not belong to the caller's job. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the function, 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this 
error occurs while using the DCL CLI, please report 
the problem to DIGITAL by means of a Software 
Performance Report (SPR). 


RTL-12 








Run-Time Library Routines 

LIB$BBCCI 


LIB$BBCCI—Test and Clear Bit with 

Interlock 


LIB$BBCCI tests and clears a selected bit under memory interlock. 
LIB$BBCCI makes the VAX BBCCI instruction available as a callable 
procedure. 

FORMAT 

LIB$BBCCI position,base 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

State of the bit before it was cleared by LIB$BBCCI; 1 if the bit was previously 
set and 0 if the bit was previously clear. 

ARGUMENTS 

position 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Bit position, relative to base, of the bit which LIB$BBCCI tests and clears. 

The position argument is the address of a signed longword integer containing 
the bit position. A position of zero denotes the low-order bit of the byte base. 
The bit position is equal to the offset of the bit chosen from the base position. 
This offset may span the entire range of a signed longword integer; negative 
offsets access bits in lower-addressed bytes. 


base 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

Address of the byte containing bit zero of the field that LIB$BBCCI references. 
The base argument is the address of the base position. The bit that 
LIB$BBCCI tests and clears is position bits offset from the low bit of base. 

DESCRIPTION 

The single bit specified by position and base is tested, the previous state of 
the bit remembered, and the bit cleared. The reading of the state of the bit 
and its clearing are interlocked against similar operations by other processors 
or devices in the system. The remembered previous state of the bit is then 
returned as the function value of LIB$BBCCI. 


For more information, see the VAX-11 Architecture Reference Manual. 
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CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 


C+ 

C This FORTRAN program demonstrates the use of 
C LIBIBBCCI. 

C- 

INTEGER*4 STATES(4) ! 128 shared state bits 

COMMON /STATES/ STATES ! Could be shared memory 
L0GICAL*4 LIBIBBCCI 

IF (LIB$BBCCI (42, STATES)) THEN 
TYPE State bit 42 was set' 

ELSE 

TYPE State bit 42 was clear' 

END IF 
END 


This FORTRAN example tests and clears bit 42 of array STATES, which is in 
a COMMON area (possibly shared between two processors). 

The output generated by this program is as follows: 

$ RUN STATE 

State bit 42 was clear. 
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LIB$BBSSI—Test and Set Bit with 

Interlock 


LIB$BBSSI tests and sets a selected bit under memory interlock. 
LIB$BBSSI makes the VAX BBSSI instruction available as a callable 
procedure. 

FORMAT 

LI B$ B BSS 1 position , base 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The state of the bit before it was set by LIB$BBSSI; 1 if it was previously set, 

0 if it was previously clear. 

ARGUMENTS 

position 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Bit position, relative to base, of the bit which LIB$BBSSI tests and sets. The 
position argument is the address of a signed longword integer containing the 
bit position. A position of zero denotes the low-order bit of the byte base. 

The bit position is equal to the offset of the bit chosen from the base position. 
This offset may span the entire range of a signed longword integer; negative 
offsets access bits in lower-addressed bytes. 


base 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

Address of the byte containing bit zero of the field that LIB$BBSSI references. 
The base argument is the address of the base position. The bit that LIB$BBSSI 
tests and sets is position bits offset from the low bit of base. 

DESCRIPTION 

The single bit specified by position and base arguments is tested, the 
previous state of the bit remembered, and the bit set. The reading of the state 
of the bit and its setting are interlocked against similar operations by other 
processors or devices in the system. The remembered previous state of the bit 
is then returned as the function value of LIB$BBSSI. 


For more information, see the VAX-11 Architecture Reference Manual. 
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CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 


C+ 

C This FORTRAN example program demonstrates 
C the use of LIB$BBSSI. 

C- 

INTEGER+4 STATES(4) ! 128 shared state bits 

COMMON /STATES/ STATES ! Could be shared memory 
L0GICAL*4 LIB$BBSSI 
IF (LIBIBBSSI (104, STATES)) THEN 
TYPE *,'State bit 104 was set' 

ELSE 

TYPE State bit 104 was clear' 

END IF 
END 


This FORTRAN example tests and sets bit 104 of array STATES, which is in 
a COMMON storage area (possibly shared between two processors). 

The output generated by this program is as follows: 

$ RUN STATEB 

State bit 104 was clear. 
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LIB$CALLG—Call Procedure with General 

Argument List 


LIB$CALLG calls a procedure with an argument list specified as an 
array of longwords, the first of which is a count of the remaining 
longwords. LIB$CALLG is a callable version of the VAX CALLG 
instruction. 

FORMAT 

LI B$CALLG arglist procedure 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 


Return value, if any, of the called procedure. This value is not changed by 
LIB$CALLG. 

ARGUMENTS 

arglist 

VMS Usage: arg_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Argument list which LIB$CALLG uses to call the specified procedure. The 
arglist argument is the address of an array of longwords containing the 
argument list. The first longword must contain the count of the remaining 
longwords. The maximum value of the count is 255. 


procedure 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference,procedure reference 

Procedure which LIB$CALLG calls with the specified argument list. The 
procedure argument is the address of the procedure entry mask for this 
procedure. 

DESCRIPTION 

LIB$ CALLG is useful for calling procedures which accept variable-length 
argument lists when the number of arguments to be passed is not known 
until execution time. LIB$CALLG can also be used to call such procedures 
from strongly typed languages which require procedures to be declared as 
having a fixed number of arguments. 


For more information, see the VAX-11 Architecture Reference Manual. 
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CONDITION 

VALUES 

RETURNED 


None. 
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LIB$CHAR—Transform Byte to First 



Character of String 

LIB$CHAR transforms a single 8-bit ASCII character to an ASCII 
string consisting of a single character followed by trailing spaces, 
if needed, to fill out the string. The range of the input byte is 0 
through 255. 

FORMAT 

LI B$CH AR one-char-str ,ascii-code 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

one-char-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

ASCII character string consisting of a single character followed by trailing 
spaces, if needed, that LIB$CHAR creates when it transforms the ASCII 
character code. The one-char-str argument is the address of a descriptor 
pointing to the character string that LIB$CHAR writes. 

ascii-code 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Single 8-bit ASCII character code that LIB$CHAR transforms to an ASCII 
string. The ascii-code argument is the address of an unsigned byte containing 
the ASCII character code. 

DESCRIPTION 

LIBSCHAR is the inverse of LIB$ICHAR. (See the description of LIB$ICHAR.) 
LIB$CHAR is not a binary-to-ASCII conversion routine. LIB$CHAR merely 
interprets ascii-code as an ASCII character code and converts it to a string. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_STRTRU Procedure successfully completed, but the string 

was truncated. The fixed-length destination string 
could not contain all of the characters. 
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LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$CRC— 

—Calculate a Cyclic Redundancy 
Check (CRC) 

LIB$CRC calculates the cyclic redundancy check (CRC) for a data 
stream. LIB$CRC makes the VAX CRC instruction available as a 
callable procedure. 

FORMAT 

LI B$CRC table , inicrc,stream 

RETURNS 

VMS Usage: longword__unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The computed cyclic redundancy check. 

ARGUMENTS 

table 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

The 16-longword cyclic redundancy check table, created by a call to 
LIB$CRC_TABLE. The table argument is the address of a signed longword 
integer containing this table. Because this table is created by LIB$CRC_ 
TABLE and then used as input in LIB$CRC, your program must call 
LIB$CRC_TABLE before it calls LIB$CRC. 

inicrc 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Initial cyclic redundancy check. The inicrc argument is the address of a 
signed longword integer containing the initial cyclic redundancy check. 

stream 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Data stream for which LIB$CRC is calculating the CRC. The stream argument 
is the address of a descriptor pointing to the data stream. 
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DESCRIPTION Before your program can call LIB$CRC, it must call LIB$CRC_TABLE. 

LIB$CRC_TABLE takes a polynomial as its input and builds the table that 
LIB$CRC uses to calculate the CRC. 

LIB$CRC allows your high-level language program to use the CRC 
instruction, which calculates the Cyclic Redundancy Check. This instruction 
checks the integrity of a data stream by comparing its state at the sending 
point and the receiving point. Each character in the data stream is used to 
generate a value based on a polynomial. The values for each character are 
then added together. This operation is performed at both ends of the data 
transmission, and the two result values compared. If the results disagree, 
then an error occurred during the transmission. 

See the VAX-11 Architecture Reference Manual for a description of the 
algorithms used in computing the CRC. 


CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 


For an example of using LIB$CRC, refer to the BASIC example at the end of 
the description of LIB$CRC_TABLE. 
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LIB$CRC_TABLE—Construct a Cyclic 



Redundancy Check 
(CRC) Table 

LIB$CRC_TABLE constructs a 16-longword table that uses a cyclic 
redundancy check polynomial specification as a bit mask. 

FORMAT 

LIB$CRC_TABLE poly /table 

RETURNS 

None. 

ARGUMENTS 

poly 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

A bit mask indicating which polynomial coefficients are to be generated 
by LIB$CRC_TABLE. The poly argument is the address of an unsigned 
longword integer containing this bit mask. 

table 

VMS Usage: longword—signed 

type: longword integer (signed) 

access: write only 

mechanism: by reference, array reference 

The 16-longword table that LIB$CRC_TABLE produces. The table argument 
is the address of a signed longword integer containing the table. 


DESCRIPTION The table created by LIB$CRC_TABLE can be passed to the LIB$CRC 

procedure for generating the cyclic redundancy check value for a stream of 



characters. 

For a description of how LIB$CRC_TABLE actually generates the table, see 
the VAX-11 Architecture Reference Manual. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


1 XTITLE "Demonstate LIB$CRC and LIB$CRC_TABLE" 

7.SBTTL "Declarations" 

%IDENT "1-001" 

! + 

! FACILITY: 

! 

! VAX/VMS Run-time library 

i 

! FUNCTIONAL DESCRIPTION: 

i 

! This program demonstates the use of LIB$CRC and LIB$CRC_TABLE. 

; 

! IMPLICIT INPUTS: 

i 

! The user is requested to enter two strings. 

i 

! IMPLICIT OUTPUTS: 

i 

! Output is printed to the controlling terminal. 

i 

! SIDE EFFECTS: 

j 

! None 

! 

! AUTHOR: 

i 

! Ken Cowan 

j 

! CREATION DATE: 22-Feb-1985 

j 

! MODIFICATION HISTORY: 


OPTION TYPE = EXPLICIT 


DECLARE LONG 
LONG 
LONG 
STRING 
STRING 


CRC_TABLE(15), 
CRC_VAL_1. 
CRC_VAL_2. 
DATA.l, 

DATA_2 


EXTERNAL LONG FUNCTION LIB$CRC 
EXTERNAL SUB LIB$CRC_TABLE 


! CRC table array & 

! CRC for first stream & 

! CRC for second stream A 
! First data stream & 

! Second data stream 

! Rtn to calculate CRC 
! Rtn to set up table for CRC 


OPEN "SYS$INPUT:" FOR INPUT AS FILE 1% 


! + 

! Initialize the CRC table. Use the CRC-16 polynomial (ref pp 305, 
! "VAX Architecture Handbook"). This is the polynomial used by 
! DDCMP and Bisync. 


CALL LIB$CRC_TABLE( O'120001'L. CRC.TABLEQ BY REF ) 

! + 

! Get data from user, 
f - 

LINPUT #17., 'Enter string: ' ;DATA_1 
!♦ 

! Calc the CRC for the user's input. This CRC polynomial needs 
! an initial CRC of 0 (ref pp 305, "VAX Architecture Handbook"). 

! LIBSCRC returns a longword, but only the low order word is valid 
! for this polynomial, 
j - 

CRC_VAL_1 = LIB$CRC( CRC.TABLEQ BY REF, 07., DATA.l ) 

CRC.VAL.l = CRC.VAL.l AND 327677. 

! + 

! Get more data from user. 

i - 
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LINPUT #1*/., 'Enter a second string: ' ;DATA_2 

CRC_VAL_2 = LIB$CRC( CRC.TABLEQ BY REF, 0*/., DATA.2 ) 
CRC_VAL_2 = CRC_VAL_2 AND 32767*/. 


! Tell the user the results of the CRC comparison. 

; - 

IF CRC_VAL_1 = CRC_VAL_2 
THEN 

PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were the same" 

ELSE 

PRINT "The two CRCs";CRC_VAL_1;" and ";CRC_VAL_2;" were the different" 
END IF 

IF DATA.l = DATA.2 
THEN 

PRINT "The two strings were the same" 

ELSE 

PRINT "The two strings were different" 

END IF 
END 


This BASIC example program shows the use of LIB$CRC and LIB$CRC_ 
TABLE. One example of the output generated by this program is as follows: 

$ RUN CRC 

Enter string: DOVE 

Enter a second string: HOSE 

The two CRCs 29915 and 29915 were the same 

The two strings were different 


April 1986 
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LIB$CREATE—DIR—Create a Directory 



LIB$CREATE_DIR creates a directory or subdirectory. 

FORMAT 

LIB$CREATE_DIR dev-dir-spec[,owner-UlC] 

[, prot-enable] [,prot-value] 
[,max-versions] [,rvn] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dev-dir-spec 

VMS Usage: device—name 
type: character string 

access: read only 

mechanism: by descriptor 

Directory specification of the directory or subdirectory that LIB$CREATE_DIR 
will create. The dev-dir-spec argument is the address of a descriptor pointing 
to this directory specification. 

The format of the dev-dir-spec string conforms to standard Record 
Management Services (RMS) format. This specification must contain a 
directory or subdirectory specification. It may contain a disk specification. 
SMD$:[THIS.IS.IT] is an example of a standard RMS file specification, 
where SMD$ is the disk specification and [THIS.IS.IT] is the subdirectory 
specification. 

This specification cannot contain a node name, file name, file type, file 
version, or wildcard characters. The maximum size of this string is 255 
characters. 

owner- UIC 

VMS Usage: uic 

type: longword (unsigned) 

access: read only 

mechanism: by reference 

User Identification Code (UIC) identifying the owner of the created directory 
or subdirectory. The owner-UIC argument is the address of an unsigned 
longword that contains the UIC. If owner-UIC is zero, the owner UIC is that 
of the parent directory. 

This is an optional argument. The default is the UIC of the parent directory 
except when the directory is in UIC format. For a directory in UIC format, for 
example [123,321], the UIC of the created directory is used. 
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prot-enable 

VMS Usage: mask_word 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Mask specifying the bits of prot-value to be set. The prot-enable argument 
is the address of an unsigned word containing this protection mask. 

Figure RTL-1 shows the structure of a protection mask. Access is allowed for 
bits set to zero. 

Figure RTL-1 Structure of a Protection Mask 


WORLD GROUP OWNER SYSTEM 



ZK-1979-84 


Set bits in the prot-enable mask cause corresponding bits of prot-value to 
be set. Clear bits in the prot-enable mask cause corresponding bits of prot- 
value to take the value of the corresponding bit in the parent directory's file 
protection. Bits in the parent directory's file protection which indicate delete 
access will not cause corresponding bits of prot-value to be set, however. 

Following is an example of how the prot-value protection mask is defined. 


Mask Name 

Hex Number 

Value 

Protection enable 

%XDBFF 

S:NONE, 0:N0NE, G:E, W:W 

Parent directory 

%X13FF 

S:RWED, 0:RWED, G:RW, W:R 

Protection value 

%X37FF 

S:RWE # 0:RWE, G:RWE, W:RW 


Prot-enable is an optional argument. It should be used only when you wish 
to change protection values from the parent directory's default file protection. 
The default for prot-enable is a mask of all zero bits, which results in the 
propagation of the parent directory's file protection. If the prot-enable mask 
contains zeros, prot-value is ignored. 

prot-value 

VMS Usage: file-protection 
type: word (unsigned) 

access: read only 

mechanism: by reference 

System/Owner/Group/World protection value of the directory you are 
creating. The prot-value argument is the address of an unsigned word which 
contains this protection mask. 
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The bits of prot-value are set or cleared in the method described in the 
definition of prot-enable above. 

Prot-value is an optional argument. The default is a word of all zero bits, 
which specifies full access for all access categories. Typically, prot-value is 
not omitted unless prot-enable is also omitted. If prot-enable is omitted, 
prot-value will be ignored. 

max-versions 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Maximum number of versions allowed for files created in the newly created 
directories. The max-versions argument is the address of an unsigned word 
containing the value of the maximum number of versions. 

Max-versions is an optional argument. The default is the parent directory's 
default version limit. If specified as zero, the maximum number of versions is 
not limited. 

rvn 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Relative volume number within a volume set on which the directory or 
subdirectory is created. The rvn argument is the address of an unsigned word 
containing the relative volume number. The rvn argument is optional. The 
default is arbitrary placement within the volume set. 

DESCRIPTION 

LIB$CREATE_DIR allows the caller to indicate the owner and protection 
of the created directory or subdirectory. The caller can also indicate the 
maximum number of versions of a file which will be maintained and the 
relative volume number in which the directory or subdirectory will be created. 

CONDITION 

VALUES 

RETURNED 

SS$_CREATED Procedure successfully completed; one or more 

directories created. 

SS$_NORMAL Procedure successfully completed; all specified 

directories already exist. 

LIB$_INVARG Invalid argument to Run_Time Library. Either the 

required argument was omitted, or dev-dir-spec is 
longer than 255 characters. 

LIB$_INVFILSPE Invalid file specification. Either the file specification 

did not contain an explicit directory and device 
name, or it contained a node name, file name, file 
type, file version, or wildcard. This error is also 
produced if the device specified was not a disk. 

Any condition values returned by $ASSIGN. 

Any condition values returned by $DASSGN. 

Any condition values returned by SPARSE. 
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Any condition values returned by $QIO. 

Any condition values returned by LIB$ANALYZE_SDESC. 
Any condition values returned by LIB$GET_EF. 
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LIB$CREATE_USER_VM_ZONE 

Create User-Defined Storage Zone 

LIB$CREATE_USER_VM_ZONE creates a new user-defined storage 
zone. 

FORMAT 

LIB$CREATE_USER_VM_ZONE 

zone-id 
[, user-arg] 

[,user-get-rtn] 
[,user-free-rtn] 

[, user-reset-rtn] 

[, user-delete-rtn] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 

zone-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 



Zone identifier. The zone-id argument is the address of a longword which is 
set to the identifier of the newly created zone. 


user-arg 

VMS Usage: user—arg 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

User argument. LIB$CREATE—USER_VM_ZONE copies the value of 
user-arg and supplies the value to all user routines invoked. 


user-get-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User allocation routine. The user-get-rtn argument is the address of the 
procedure entry mask for the optional user routine that is invoked each time 
LIB$GET_VM is called for the zone. 
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user-free-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User deallocation routine. The user-free-rtn argument is the address of the 
procedure entry mask for the optional user routine that is invoked each time 
LIB$FREE_VM is called for the zone. 


user-reset-rtn 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
function call (before return) 
by reference, procedure reference 


User routine to reset the zone. The user-reset-rtn argument is an optional 
user routine that is invoked each time LIB$RESET_VM_ZONE is called for 
the zone. 


user-delete-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User routine to delete the zone. The user-delete-rtn argument is an optional 
user routine that is invoked when LIB$DELETE_VM—ZONE is called for the 
zone. 


DESCRIPTION LIB$CREATE_USER—VM_ZONE creates a user-defined zone. If an error 

status is returned, the zone is not created. 

Each time that one of the heap management procedures (LIB$GET_VM, 
LIB$FREE_VM, LIB$RESET_VM_ZONE, or LIB$DELETE_VM_ZONE) is 
called to perform an operation on a user-defined zone, the corresponding user 
routine that you supplied is called to perform the actual operation. 

You may omit any of the optional user routines. However, if you omit a 
routine and later call the corresponding heap management procedure, the 
error status LIB$_INVOPEZON will be returned. 

Call Format for User Routines 

The user routines are called with arguments similar to those passed to 
LIBSGET_VM, LIBSFREE—VM, LIBSRESET—VM_ZONE, or LIB$DELETE_ 
VM—ZONE. In each case, the user-arg argument from LIB$CREATE_USER— 
VM—ZONE is passed to the user routine rather than passing a zone-id 
argument. 

The call format for a user get or free routine is as follows: 

u««r-rtn num-bytes .base-adr .user-arg 
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CONDITION 

VALUES 

RETURNED 


num-bytes 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of contiguous bytes to allocate or free. The num-bytes argument is 
the address of a longword integer containing the number of bytes. The value 
of num-bytes must be greater than zero. 

base-adr 

VMS Usage: address 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

First virtual address of the contiguous block of bytes allocated or freed. The 
base-adr argument is the address of an unsigned longword containing this 
base address. (This argument is write only for a get routine, and read only 
for a free routine.) 

user-arg 

VMS Usage: user_arg 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

User argument. LIB$CREATE_USER_VM_ZONE copies user-arg as it is 
supplied to all user routines invoked. 

The status value returned by your routine is returned as the status value for 
the corresponding call to LIB$GET_VM or LIB$FREE—VM. 

The call format for a user reset or delete routine is as follows: 

us«r-rtn user-arg 

user-arg 

VMS Usage: user-arg 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

User argument. LIB$CREATE_USER—VM_ZONE copies user-arg as it is 
supplied to all user routines invoked. 

The status value returned by your routine is returned as the status value for 
the corresponding call to LIB$RESET_VM_ZONE or LIB$DELETE_VM_ 
ZONE. 


SSS—NORMAL 

LIB$_INSVIRMEM 


Normal successful completion. 
Insufficient virtual memory. 
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LIB$CREATE_VM_ZONE—Create a New 

Zone 



LIB$CREATE_VM_ZONE creates a new storage zone according to 
specified arguments. 

FORMAT 

LI B$CREATE_VM_ZON E zone-id [algorithm] 

[,algorithm-arg] [, flags] 
[,extend-size] 

[,initial-size] 

[, block-size] [, alignment] 

[, page-limit] [,p 1 ] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

zone-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Zone identifier. The zone-id argument is the address of a longword that is 
set to the zone-id of the newly created zone. 

algorithm 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Algorithm. The algorithm argument is the address of a longword integer 
which contains the code for one of the LIB$VM algorithms: 

1 LIB$K_VM_FIRST_FIT First fit 

2 LIB$K_VM_QUICK_FIT Quick fit, lookaside list 

3 LIB$K_VM_FREQ_SIZES Frequent sizes, lookaside list 

4 LIB$K_VM_FIXED Fixed size blocks 

If algorithm is not specified, a default of 1 (first fit) is used. 
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algorithm-arg 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Algorithm argument. The algorithm-arg argument is the address of a 
longword integer which contains a value that is specific to the particular 
allocation algorithm. 


Algorithm 

Value of algorithm-arg 


First fit 

Not used, may be omitted. 


Quick fit 

The number of lookaside lists used, 
lists must be between 1 and 128. 

The number of 

Frequent sizes 

The number of lookaside lists used, 
lists must be between 1 and 16. 

The number of 

Fixed size blocks 

The fixed request size for each get or free. The 
request size must be greater than 0. 


The algorithm-arg argument must be specified if you are using the quick 
fit, frequent sizes or fixed size blocks algorithms. However, this argument is 
optional if you are using the first fit algorithm. 


flags 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Flags. The flags argument is the address of a longword integer which 
contains flag bits that control various options: 


Bit 

Value 

Description 

Bit 0 

LIB$M_VM_BOUNDARY_ 

TAGS 

Boundary tags for faster freeing 

Adds a minimum of eight bytes to 
each block 

Bit 1 

LIB$M_VM_GET_FILLO 

LIB$GET_VM : fill with bytes of 0 

Bit 2 

LIB$M_VM_GET_FILL 1 

LIB$GET_VM : fill with bytes of FF 
(hexadecimal) 

Bit 3 

LIB$M_VM_FREE_FILLO 

LIB$FREE_VM : fill with bytes of 0 

Bit 4 

LIB$M_VM_FREE_FILL1 

LIB$FREE_VM : fill with bytes of FF 
(hexadecimal) 

Bit 5 

LIB$M_VM_EXTEND_AREA 

Add extents to existing areas if 
possible 


Bits 6:31 are reserved and must be 0. 

This is an optional argument. If flags is omitted, the default of 0 (no fill and 
no boundary tags) is used. 
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extend-size 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Zone extend size. The extend-size argument is the address of a longword 
integer which contains the number of (512-byte) pages to be added to the 
zone each time it is extended. 


The value of extend-size must be between 1 and 1024. 

This is an optional argument. If extend-size is not specified, a default of 16 
pages is used. 


Note: Extend-size does not limit the size of blocks that can be allocated from 
the zone. The actual extension size is the maximum of extend-size and 
the number of pages needed to satisfy the LIB$GET_VM call that caused 
the extend. 


initial-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Initial size for the zone. The initial-size argument is the address of a 
longword integer which contains the number of (512-byte) pages to be 
allocated for the zone as the zone is created. 


This is an optional argument. If initial-size is not specified or 0, no pages 
are allocated when the zone is created. The first call to LIB$GET_VM for the 
zone allocates extend-size pages. 


block-size 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Block size of zone. The block-size argument is the address of a longword 
integer specifying the allocation quantum (in bytes) for the zone. All blocks 
allocated are rounded up to a multiple of block-size. 


The value of block-size must be a power of two between 8 and 512. This is 
an optional argument. If block-size is not specified, a default of 8 bytes is 
used. 


alignment 


VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Block alignment. The alignment argument is the address 
integer which specifies the required address alignment (in 
block allocated. 


of a longword 
bytes) for each 


The value of alignment must be a power of 2, between 4 and 512. This is 
an optional argument. If alignment is not specified, a default of 8 is used 
(quadword alignment). 
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page-limit 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Maximum page limit. The page-limit argument is the address of a longword 
integer which specifies the maximum number of (512-byte) pages that can 
be allocated for the zone. The value of page-limit must be between 0 and 
32767. 

This is an optional argument. If page-limit is not specified or 0, the only 
limit is the total process virtual address space limit imposed by VMS. 

pi 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Smallest block size. The pi argument is the address of a longword integer 
which specifies the smallest block size (in bytes) that has a lookaside list for 
the quick fit algorithm. 

If pi is not specified, the default of block-size is used. That is, lookaside lists 
are provided for the first n multiples of block-size. 

DESCRIPTION 

LIB$CREATE_VM_ZONE creates a new storage zone. The zone-id value 
that is returned can be used in calls to LIB$GET_VM, LIB$FREE_VM, 
LIB$RESET_VM_ZONE, and LIB$DELETE_.VM_ZONE. 

If an error status is returned, the zone is not created. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion 

LIB$_INSVIRMEM Insufficient virtual memory 

LIBS—INVARG Invalid argument 
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LIB$CRF_INS_KEY—Insert Key in Cross- 



Reference Table 

LIB$CRF_INS_KEY inserts information about a key into a cross- 
reference table. 

FORMAT 

LIB$CRF_INS_KEY ctl-tbl,keyl ,vaH ,flags 

RETURNS 

None. 

ARGUMENTS 

ctl-tbl 

VMS Usage: longword_signed 

type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

Cross-reference table into which LIB$CRF_INS_KEY inserts information 
about the key. The ctl-tbl argument is the address of a signed longword 
integer pointing to the cross-reference table. You must name this table 
each time you call a cross-reference procedure because you can accumulate 
information for more than one cross-reference table at a time. 

keyl 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

A counted ASCII string that contains a symbol name or an unsigned binary 
longword. The keyl argument is the address of a descriptor pointing to the 
key. 

vail 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Symbol value, the address of which LIB$CRF_INS—KEY inserts in the 
cross-reference table. The vail argument is the address of a signed longword 
integer containing this value. Both the key and value addresses must be 
permanent addresses in the user's symbol table. 
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flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value used in selecting the contents of the KEY2 and VAL2 fields; flags is 
stored with the entry. The flags argument is the address of an unsigned 
longword containing the flags. When preparing the output line, LIB$CRF_ 
OUTPUT uses flags and the 16-bit mask in the field descriptor table to extract 
the data. The high-order bit of the word is reserved for LIB$CRF_INS_KEY. 


DESCRIPTION LIB$CRF_INS_KEY stores information to be printed in the KEY1, KEY2, 

VAL1, and VAL2 fields. When you call this procedure, an entry for the key is 

made in the cross-reference table if the key is not present in the table. If the 

key is present, only the value address and value flag fields are updated. 

Using LIB$CRF_INS_KEY involves the following steps: 

• Define a table of control information, using the $CRFCTLTABLE macro. 

• Define each field of the output line, using the $CRFFIELD macro. 

• Specify the end of each set of macros that define a field in the output line, 
using the $CRFFIELDEND macro. 

• Provide data by calling LIB$CRF_INS_KEY to insert an entry for the 
specify key in the specified symbol table. This data is used to build tables 
in virtual memory. 

• Call LIB$CRF_OUTPUT, the cross-reference output procedure, to 
summarize and format the data. Supply a routine that LIB$CRF_OUTPUT 
calls to print each line in the output file. Because you supply this routine, 
you can control the number of lines per page and the header lines. 


CONDITION None. 

VALUES 

RETURNED 
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LIB$CRF_INS_REF—Insert Reference to 



a Key in the Cross- 
Reference Table 

LIB$CRF_INS_REF inserts a reference to a key in a cross-reference 
symbol table. 

FORMAT 

LIB$CRF_INS_REF ctl-tbl,key1 ,ref2 ,ref1 ,ref-def 

RETURNS 

None. 

ARGUMENTS 

ctl-tbl 

VMS Usage: vector_longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

Control table associated with this cross-reference. The ctl-tbl argument is the 
address of an array containing the control table. 

keyl 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Key referred to by LIB$CRF_JNS_REF. The keyl argument is the address of 
a signed longword integer containing the key. The key is a counted ASCII 
string that contains a symbol name or an unsigned binary longword. It must 
be a permanent address in the user's symbol table. 

ref2 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Counted ASCII string with a maximum of 31 characters, not including the 
byte count. The ref2 argument is the address of a descriptor pointing to the 
counted ASCII string. 
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refl 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

The 16-bit value used in selecting the contents of the REF1 field. The refl 
argument is the address of a signed longword integer containing this value. 
When preparing the output line, LIB$CRF_OUTPUT uses refl and the bit 
mask in the field descriptor table to extract the data. The high-order bit of 
the word is reserved for LIB$CRF_INS_REF. 


ref-def 


VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
read only 
by reference 


Reference/definition indicator that LIB$CRF_JNS_REF uses to distinguish 
between a reference to a symbol and the definition of the symbol. The 
ref-def argument is the address of a signed longword integer containing this 
indicator. The only difference between processing a symbol reference and a 
symbol definition is where LIB$CRF_INS_REF stores the information. 


The indicator can have either of the following values: 


Symbolic 

Name 

Description 

CRF$K_REF 

Reference to a symbol 

CRF$K_DEF 

Definition of a symbol 


DESCRIPTION LIB$CRF_INS_REF inserts a reference to a key in the cross-reference symbol 

table. If you attempt to insert reference information for a key that was 
not specified in a call to LIB$CRF_JNS_KEY, LIB$CRF_JNS_REF uses 
the address of the key to locate the symbol name and set the KEY1 field. 
Once set, either as a result of LIB$CRF_INS-KEY or LIB$CRF_INS_REF, 
the KEY1 field is never changed. A KEY1 field set by LIB$CRF_INS_REF 
has a space-filled VAL1 field associated with it unless it is overridden by a 
subsequent call to LIB$CRF_INS_KEY. 

Using LIB$CRF_INS_REF involves the following steps: 

1 Define a table of control information, using the $CRFCTLTABLE macro. 

2 Define each field of the output line, using the $CRFFIELD macro. 

3 Specify the end of each set of macros that define a field in the output line, 
using the SCRFFIELDEND macro. 

4 Provide data by calling LIB$CRF_INS__REF to insert a reference to a key 
in the specified symbol table. This data is used to build tables in virtual 
memory. 

5 Call LIB$CRF_OUTPUT, the cross-reference output procedure, to 
summarize and format the data. Supply a routine that LIB$CRF_OUTPUT 
calls to print each line in the output file. Because you supply this routine, 
you can control the number of lines per page and the header lines. 
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CONDITION 

VALUES 

RETURNED 


None. 
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LIB$CRF_OUTPUT—Output Cross- 



Reference Table 
Information 

LIB$CRF_OUTPUT extracts the information from the cross-reference 
tables and formats the output pages. 

FORMAT 

LIB$CRF_OUTPUT ctl-tbl, width ,pagl ,pag2 

, mo de-in d, del-sav-ind 

RETURNS 

None. 

ARGUMENTS 

ctl-tbl 

VMS Usage: vector_longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

Control table associated with the cross-reference. The ctl-tbl argument is 
the address of an array containing the control table. The table contains 
the address of the user-supplied routine that prints the lines formatted by 
LIB$CRF_OUTPUT. 

width 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Width of the output line. The width argument is the address of a signed 
longword integer containing the width. 

pagl 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of lines on the first page of the output. The pagl argument is the 
address of a signed longword integer containing this number. This allows 
the user to reserve space to print header information on the first page of the 
cross-reference. 
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pag2 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of lines per page for the other pages. The pag2 argument is the 
address of a signed longword integer containing this number. 


mode-ind 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Output mode indicator. The mode-ind is the address of a signed longword 
integer containing the mode indicator. 


This indicator allows the user to select which of three output modes is 
desired. 


Output Mode 

Description 

CRF$K_VALUES 

Only the value and key fields are to be printed. LIB$CRF_ 
OUTPUT creates multiple columns across the page. Each 
column consists of the KEY 1, KEY2, VAL1, and VAL2 
fields. A minimum of one space between each column is 
guaranteed. 

CRF$K_V ALS—REFS 

Requests a cross-reference summary that has no column 
space saved for a defining reference. If the user inserted 
a reference with the CRF$K_DEF indicator, the entry is 
ignored. 

CRF$K_DEFS_REFS 

Requests a cross-reference summary with the first REF1 
and REF2 fields used only for definition references. If no 
definition reference is provided, the fields are space filled. 

del-sav-ind 


VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Delete/save indicator which LIB$CRF_OUTPUT uses to determine whether 
the table's built-in accumulating symbol information is to be saved or deleted 
once the cross-reference is produced. The del-sav-ind is the address of a 
signed longword integer containing the delete/save indicator. 


The indicator can be either of the following: 


CRF$K_SAVE To preserve the tables for subsequent processing 
CRF$K_DELETE To delete the tables 


DESCRIPTION LIB$CRF_OUTPUT can format output lines for three types of cross-reference 

listings. 

1 A summary of symbol names and their values, as illustrated in 
Figure RTL-2. 
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2 A summary of symbol names, their values, and the names of modules that 
refer to the symbol, as illustrated in Figure RTL-3. 

3 A summary of symbol names, their values, the name of the defining 
module, and the names of those modules that refer to the symbol, as 
Figure RTL-4 shows. 

Figure RTL-2 Summary of Symbol Names and Values 
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Regardless of the format of the output, LIB$CRF_OUTPUT considers the 
output line as consisting of six different field types. 


KEY 1 
KEY2 

VAL1 

VAL2 

REF1 and REF2 fields 


Is the first field in the line. It contains a symbol 
name. 

Is the second field in the line. It contains a set of 
flags (for example, -R) that provide information 
about the symbol. 

Is the third field in the line. It contains the value of 
the symbol. 

Is the fourth field in the line. It contains a set of 
flags describing VAL1. 

Within each REF1 and REF2 pair, REF1 provides 
a set of flags and REF2 provides the name of a 
module that references the symbol. 


Any of these fields can be omitted from the output. 
For example: 


Symbol Value 


Symbol Value 


BASIINSTR 

KEY1 

Symbol 


000020BO-RU 
VAL1 VAL2 
Value 


BASISCRATCH 

KEY1 

Defined By 


00002308-RU 
VAL1 VAL2 
Referenced By ... 


LIB$FREE_VM 0001E185-R LIB$VM 


ALLGBL 


KEY1 


VAL1 VAL2 


REF2 REF2 

(CRF$K_DEF) (CRF$K_REF) 


CONDITION None. 

VALUES 

RETURNED 
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LIB$CURRENCY—Get System Currency 



Symbol 

LIB$CURRENCY returns the system's currency symbol. 

FORMAT 

LI B$C U R R E N C Y currency-str [, out-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

currency-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Currency symbol. The currency-str argument is the address of a descriptor 
pointing to the currency symbol. 

out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of characters that LIB$CURRENCY has written into currency-str, not 
counting padding in the case of a fixed-length string. The out-len argument 
is the address of an unsigned word containing the length of the currency 
symbol. If the input string is truncated to the size specified in the currency- 
str descriptor, out-len is set to this size. Therefore, out-len can always be 
used by the calling program to access a valid substring of currency-str. 

DESCRIPTION 

LIB$CURRENCY attempts to translate the logical name SYS$CURRENCY as 
a process, group, or system logical name, in that order. If the translation fails, 
the routine returns the United States currency symbol ( $ ). If the translation 
succeeds, the text produced is returned. Thus, a system manager can define 
SYS$CURRENCY as a system-wide logical name to provide a default for all 
users, and an individual user with a special need can define SYS$CURRENCY 
as a process logical name to override the system default. 

For example, if you wish to use the British pound sign as the currency symbol 
within your process, but wish to leave the dollar sign as the system's default, 
define SYS$CURRENCY to be the pound sign (#) in your process logical 
name table. After this, any call to LIB$CURRENCY within your process 
returns the pound sign (# ), while any call outside your process returns the 
dollar sign ($ ). 

LIB$CURRENCY is implicitly used by BASIC. 
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CONDITION 

SS$_NORMAL 

Procedure successfully completed. 

VALUES 

LIB$_STRTRU 

Successfully completed, but the currency string 

RETURNED 


was truncated. 


LIB$_FATERRLIB 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


LIB$_INSVIRMEM 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 


LIB$_INVSTRDES 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 


EXAMPLE 

10 ! ♦ 

! This BASIC program uses LIB$CURRENCY to 
! return the default system currency symbol, 
i - 

OUTLEN = 1 

CALL LIB$CURRENCY (CURR$, OUTLEN) 

PRINT CURR$ 

99 END 


The BASIC program listed above uses LIB$CURRENCY to display the system 
currency symbol default. The output generated by the program is a dollar 
sign ($). 
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LIB$CVT_DX_DX—General Data Type 



Conversion Routine 

LIB$CVT_DX_DX converts a VAX standard atomic or string datum 
described by a source descriptor to another VAX standard atomic or 
string datum described by a destination descriptor. This conversion 
is supported over a subset of the VAX standard data types. 

FORMAT 

LIB$CVT_DX_DX src ,dst[,dst-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

src 

VMS Usage: address 
type: _ unspecified 

access: read only 

mechanism: by descriptor 

Source item to be converted by LIBCVT_DX_DX. The src argument is the 
address of a descriptor pointing to the source item to be converted. The type 
of the item to be converted is contained in the descriptor. 

The combinations of class and data type of the source descriptor are restricted 
as described in Tables RTL-1, RTL-2, and RTL-3. 

dst 

VMS Usage: address 
type: unspecified 

access: write only 

mechanism: by descriptor 

Destination of the conversion. The dst argument is the address of a descriptor 
pointing to the destination item. The destination descriptor specifies the data 
type to which the source item is converted. 

The combinations of class and data type of the destination descriptor are 
restricted as described in Tables RTL-1, RTL-2, and RTL-3. 
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dst-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Length in bytes of the destination item (when that item is a string) that has 
been converted by LIB$CVT_DX_DX, not including any space filling. The 
dst-len argument contains the address of an unsigned word containing this 
length. 


If the destination string is truncated, the returned length reflects the 
truncation. This word can be used by the calling program to determine if 
truncation has occurred or to extract the exact length of the string when the 
string contains space filling. 


DESCRIPTION LIB$CVT_DX_DX is a universal conversion utility routine. Although some 

of the functions of this routine may be found in other Run-Time Library 
routines, LIB$CVT_DX_DX packages the conversion functions with a general 
interface. Because of this general interface, the calling program does not have 
to specify what conversion should be done for which data type. 

The description of this routine has been divided into the following parts: 

• Guidelines for Using LIB$CVT_DX_DX 

• Use of Numeric Byte Data Strings 

Guidelines for Using LIB$CVT_DX_DX 

The data type and descriptor class of the source and destination arguments 
determine how LIB$CVT_DX_DX performs the conversion, according to the 
rules listed below. 

• Conversion is defined over three sets of data types: atomic, string, and 
numeric byte data strings (NBDS). (For more information about numeric 
byte data strings, see the next section "Use of Numeric Byte Data Strings.") 
Although the set of data types in NBDS is actually a subset of the atomic 
and string data types, the three sets are mutually exclusive in this routine. 

• Scale is applied when indicated in the descriptor (DSC$K_CLASS_SD 
only) and scaling is defined for the data type. 

• No language-specific semantics are applied, such as BASIC scale for 
DSC$K_DTYPE_D. 

• Some conversions must use intermediate values to arrive at the destination 
requested. Although some loss of speed is inevitable, intermediate values 
will not cause a loss of precision. 

• Results are always rounded instead of truncated, except for the case 
described in below. Note that loss of precision or range may be inherent 
in the destination data type or in the NBDS destination size. No errors are 
reported if there is a loss of precision or range as a result of destination 
data type. 

• When the destination is an NBDS, and has fixed-string semantics, then 
if the source does not fill the destination, the destination is padded with 
blanks. 


RTL—49 








Run-Time Library Routines 

LI B$C VT—DX—DX 


• When the source and destination are both NBDS, and no scaling is 
requested, then a straight copy is done without translation or conversion, 
and truncation is possible. If scaling is requested, then a conversion takes 
place as defined in Table RTL-3. 

• When the source is an NBDS and the destination is non-NBDS, if there is 
an invalid character in the source, or the value is outside the range that 
can be represented by the destination, then LIB$_INVNBDS is returned. 

• Attempts to convert a negative value to an unsigned data type cause the 
LIB$_INVCVT error to be returned. 

• If the destination is a NBDS of class DSC$K_CLASS_D, then a new string 
of appropriate size will be allocated for it if necessary. 

• Invalid conversions resulting in an error produce an unpredictable result. 

Use of Numeric Byte Data Strings 

For simplicity, and to define a generic numeric string that LIB$CVT_DX_DX 

understands to be a numeric string, the set Numeric Byte Data String (NBDS) 

is defined to be the set of descriptors given in Table RTL-1. 

Table RTL-1 Acceptable Subset of VAX Standard Data Types 


DSC$K_DTYPE_yyy 

DSC$K_CLASS_xxx 

A 

D 

NCA 

S 

SD 

VS 

B 







BU 

X 


X 




T 

X 

X 

X 

X 

X 

X 

VT 






X 


Note: An array will have the semantics of a fixed string. NBDS must have the format defined later. 


ZK-4260-85 


The combination of data type and descriptor class determines whether an 
argument is a NBDS. Table RTL-2 shows the combinations of descriptor class 
and data type (as specified in the fields of the descriptor) that LIB$CVT_DX_ 
DX recognizes. The combinations marked NBDS are considered NBDS's. 
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Table RTL-2 Data Types Accepted by LIB$CVT_DX_DX 


From: 

To: 


Text (decimal) 

Longword 

Text (hexadecimal) 

Longword 

Text (octal) 

Longword 

Text (binary) 

Longword 

Text (signed integer) 

Longword 

Text (logical) 

Longword 

Text (octal) 

Longword 

* 

Text (hexadecimal) 

Longword 

Text 

D_floating 

Text 

F_floating 

Text 

G _ floating 

Text 

H_floating 





Longword 

Text (binary) 

Longword 

Text (signed integer) 

Longword 

Text (logical) 

Longword 

Text (octal) 

Longword 

Text (hexadecimal) 


ZK-1942-84 


For example, LIB$CVT_DX_DX treats the combination DSC$K_DTYPE_B 
/DSC$K_CLASS_S (unsigned byte scalar) as an atomic data type. However, 
the procedure considers DSC$K_DTYPE_BU/DSC$K_CLASS_NCA 
(noncontiguous array of unsigned bytes) to be a NBDS. 

A destination NBDS is always left-justified. 

If a destination NBDS requires more than 50 digits for its format (including 
sign if any), then it is expressed in exponential format. 
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For a conversion of NBDS to NBDS, this format is used if scaling is requested. 
Otherwise, a straight copy is done. The format of a source NBDS is the 
same as the format defined for the input argument inp in OTS$_CVT_T_z, 
with bits 0, 2, and 4 set in the flags argument. That is, blanks are ignored, 
underflow causes an error and tabs are ignored. 

Table RTL-3 defines the format of a destination NBDS. 


Table RTL-3 Destination NBDS formats 


Source Data Type 

Destination NBDS Format 1 

Byte integer (signed) 

sdigits 

Byte (unsigned) 

sdigits 

Word integer (signed) 

sdigits 

Word (unsigned) 

digits 

Longword integer (signed) 

sdigits 

Longword (unsigned) 

digits 

Quadword integer (signed) 

sdigits 

D_floating 

s0.min(16,w-7)E(+ or -)nn 

F_floating 

s0.min( 7,w-7)E(+ or -)nn 

G_floating 

s0.min(15,w-8)E(+ or -)nnn 

FI_floating 

s0.min(33,w-9)E(+ or -)nnnn 

NBDS 

s0.min(33,w-9)E(+ or -)nnnn 

Decimal string 

sdigits (as defined by VAX architecture) 


1 digits—Digits 0 through 9, and a decimal point only if source descriptor specifies 
DSC$B_SCALE less than 0. 

w—Width of destination in bytes, 
s—Sign. For positive numbers the sign is implied, 
min—Minimum of two values. 


Two array descriptors, DSC$K_CLASS_A and DSC$K_CLASS_NCA, are 

supported for specific languages that describe strings using these mechanisms. 

• DSC$B_DIMCT = 1—Only one-dimensional arrays are recognized. 

• DSC$W_LENGTH = 1—The length of each array element must be a byte. 

• DSC$L_ARSIZE less than or equal to 65,535—The total size of the array 
must be less than 65,535 bytes. 

• If DSC$L_ARSIZE = 0, the array has a length of zero. 

• DSC$L_S1 = 1—The stride of an array passed by a noncontiguous array 
descriptor must be 1. That is, even if the class of the array's descriptor is 
noncontiguous array (NCA), the array itself must be contiguous. 

• An array is written with the semantics of a fixed string. 

For more information about the semantics of writing output strings, see 

Section 5.2.2. 
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CONDITION 

VALUES 

RETURNED 


If the calling program passes a descriptor to LIB$CVT_DX_DX that does not 
comply with Table RTL-2, one of the following error messages is returned: 

LIB$_INVDTYDSC 
LIB$_JN V CL ADSC 
LIB$_INVCLADTY 
LIB$_INVNBDS 


SS$_NORMAL 

LIB$_DECOVF 

LIB$_FLTOVF 

LIB$_FLTUND 

LIB$_INVCLADSC 

LIB$_INVCLADTY 


LIB$_INVCVT 

LIB$_INVDTYDSC 

LIB$_INTOVF 

LIB$_INVNBDS 


LIB$_OUTSTRTRU 

LIB$_ROPRAND 


Routine successfully completed. 

Packed decimal overflow error. Severe error. 
Floating overflow error. Severe error. 

Floating underflow error. Severe error. 

Invalid class in descriptor. This class of descriptor 
is not supported. Severe error. 

Invalid class and data type in descriptor. This 
class and data type combination is not supported. 
Severe error. 

If the source value is negative and the destination 
data type is unsigned, this error is returned. 

Invalid data type in descriptor. This data type is 
not supported. Severe error. 

Integer overflow error. Severe error. 

Invalid NBDS. There is an invalid character in the 
input, or the value is outside the range that can 
be represented by the destination, or the NMDS 
descriptor is invalid. This error is also signaled 
when the array size of an NBDS is larger than 
65,535 bytes or the array is multi-dimensional. 

Output string truncated. This is returned only when 
NBDS is both source and destination and no scaling 
is requested. The result is truncated. 

Reserved operand error. Severe Error. 
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LIB$CVT_xTB—Convert Numeric Text to 

Binary 


LIB$CVT_DTB, LIB$CVT_HTB and LIB$CVT_OTB return a binary 
representation of the ASCII text string representation of a decimal, 
hexadecimal, or octal number. 

FORMAT 

LIB$CVT_DTB count ,string,result 

LIB$CVT_HTB count ,string ,result 

LI B$CVT—OTB count, string,result 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

count 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Byte count of the input ASCII text string. The count argument is a signed 
longword integer containing the byte count of the input string. 


string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by reference 

ASCII text string representation of a decimal, hexadecimal, or octal number 
which LIB$CVT_xTB converts to binary representation. The string argument 
is the address of a character string containing this input string to be converted. 


result 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Binary representation of the input string. The result argument is the address 
of a signed longword integer containing the converted string. 
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DESCRIPTION LIB$CVT_DTB converts the ASCII text string representation of a decimal 

number into binary representation. LIB$CVT_HTB converts the ASCII text 
string representation of a hexidecimal number into binary representation. 
LIB$CVT_OTB converts the ASCII text string representation of an octal 
number into binary representation. 

Note: LIB$CVT_DTB, LIB$CVT_HTB and LIB$CVT_OTB are intended to 

be called primarily from BLISS and MACRO programs. Therefore, the 
routines expect input scalar arguments to be passed by value and strings 
by reference. Blanks are invalid characters. 


CONDITION i 
VALUES 0 

RETURNED 


Procedure successfully completed. 

Nonradix character in the input string or a sign in 
any position other than the first character. Blanks 
and tabs are invalid characters. An overflow from 
32 bits (unsigned) will cause an error. 
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LIB$DATE. 

-TIME—Date and Time 

Returned as a String 

LIB$DATE_TIME returns the VAX/VMS system date and time in the 
semantics of a user-provided string. 

FORMAT 

LI B$ DATE-TIME dst-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

dst-str 

VMS Usage: date—time 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$DATE_TIME writes the system date and 
time. The dst-str argument is the address of a descriptor pointing to the 
destination string. 

This string is 23 characters long; its format is as follows: 

dd-mmm-yyyy hh : nun : ss . hh 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_STRTRU Success, but destination string was truncated. 

LIB$_INSVIRMEM Insufficient virtual memory. A call to LIB$GET_VM 

has failed because your program has exceeded the 
image quota for virtual memory. 

LIB$_INVSTRDES Invalid string descriptor. A string descriptor has an 

invalid value in its DSC$B_CLASS field. 
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EXAMPLE 

10 ! + 

! This BASIC program demonstrates the 
! use of LIB$DATE_TIME. 

i - 

CALL LIB$DATE_TIME(DSTSTR$) 

PRINT DSTSTR$ 

99 END 


This BASIC program uses LIB$DATE_TIME to display the current system 
date and time. The output generated by one run of this program was as 
follows: 

26-JUL-1984 13:41:22.67 


April 1986 
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LIB$DAY- 

—Day Number Returned as a 
Longword Integer 

LIB$DAY returns the number of days since the system zero date 
of November 17, 1858, or the number of days from November 17, 
1858, to a user-supplied date. 

FORMAT 

LI B$ DAY day-number[, user-time] [, day-time] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

day-number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Number of days since the system zero date. The day-number argument is 
the address of a signed longword integer containing the day number. 

user-time 

VMS Usage: date.time 
type: quadword integer (signed) 

access: read only 

mechanism: by reference 

User-supplied time, in 100-nanosecond units. The user-time argument is the 
address of a signed quadword integer containing the user time. A positive 
value indicates an absolute time, while a negative value indicates a delta 
time. This is an optional argument. If omitted, the default is the current 
system time. This quadword time value is obtained by calling the system 
service SYS$BINTIM. 

If time is passed as zero by value, the numeric value for the current day 
is returned. If time is passed as a zero by reference, the number returned 
represents the day of November 17th, 1858, rather than the current day. 

day-time 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Number of 10-millisecond units since midnight of the user-time argument. 
The day-time argument is the address of a signed longword integer into 
which LIB$DAY writes this number of units. 
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DESCRIPTION LIB$DAY returns the number of days since the system zero date of November 

17, 1858. Optionally, the caller can supply a time in system time format to 
be used instead of the current system time. In this case, LIB$DAY returns the 
number of days from November 17, 1858, to the user-supplied date. 

The number of 10-millisecond units since midnight is an optional return 
argument. 

Note: If the caller supplies a quadword time, it is not verified. If it is negative 
(bit 63 on), the day-number value returned is negative. 

The Run-Time Library provides the date/time utility procedures for languages 
that do not have built-in time and date functions, and for particular 
applications that require the time or date in a different format from the 
one that the language supplies. In general, it is simpler to call the Run-Time 
Library routines for the system date and time than to call a system service. 


CONDITION SS$_NORMAL 

VALUES SS$_INTOVF 

RETURNED 


Routine successfully completed. 

The optional argument user-time is present and 
represents a date past the year 8600. 


EXAMPLE 


PROGRAM DAY(INPUT, OUTPUT); 

{+> 

{ This is an example program showing the 
< use o t LIB$DAY. 

<-> 

VAR 

DAYNUMBER : INTEGER; 

PROCEDURE LIB$DAY(DAYNUM : INTEGER); 

EXTERN; 

BEGIN 

LIB$DAY(DAYNUMBER); 

WRITELN('The daynumber is DAYNUMBER); 
END. 


A sample of the output generated by this program is shown below. 


The daynumber is 2146801612 


April 1986 
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LIB$DAY_OF_WEEK—Show Numeric Day 

of Week 



LIB$DAY_OF_WEEK returns the numeric day of the week for an 
input time value. If 0 is the input time value, the current day of the 
week is returned. The days are numbered 1 through 7, with Monday 
as day 1 and Sunday as day 7. 

FORMAT 

LIB$DAY_OF_WEEK time ,day-num 

RETURNS 

VMS Usage: cond_value 
type: condition value 

access: write only 

mechanism: by value 

ARGUMENTS 

time 

VMS Usage: date_time 
type: quadword (unsigned) 

access: read only 

mechanism: by reference 

Time to be translated to a day of the week, or zero. The time argument is the 
address of an unsigned quadword containing the value of time. Time must 
be supplied as an absolute system time. To obtain this time value in proper 
quadword format call the system service SYS$BINTIM. 

If time is passed as zero by value, the numeric value for the current day 
is returned. If time is passed as a zero by reference, the number returned 
represents the day of November 17th, 1858, rather than the current day. 

day-num 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Numeric day of week. The day-num argument is the address of a longword 
into which LIB$DAY_OF_WEEK writes the integer value representing the day 
of the week. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 
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EXAMPLE 


PROGRAM DAYOFWEEKCINPUT, OUTPUT); 

{*> 

{ This is an example showing 
{ the use of LIB$DAY_OF_WEEK. 

{-> 

VAR 

OUTDAT : INTEGER; 

PROCEDURE LIB$DAY_OF_WEEK(TIM : INTEGER; %REF OUTDA : INTEGER); EXTERN; 
BEGIN 

LIB$DAY_OF_WEEK(DIMMED O, OUTDAT); 

WRITELN(OUTDAT); 


END. 


This PASCAL program shows the use of LIB$DAY_OF_WEEK. This example 
was tested on a Monday, and the output generated was "l". 







Run-Time Library Routines 

LIB$DECODE_FAULT 


LIB$DECODE_FAULT—Decode Instruction 

Stream During 

Fault 


LIB$DECODE_FAULT is a tool for building condition handlers which 
process instruction fault exceptions. It is called from a condition 
handler. 

FORMAT 

LIB$DECODE_FAULT signal-args mechanism- 

args r user-action [ f user-arg] 

[, instruction-definitions] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS signal-args 

VMS Usage: vectorJong word-unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Signal arguments array that was passed from VAX/VMS to your condition 
handler. The signal-args argument is the address of the signal arguments 
array. 

mechanism-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Mechanism arguments array that was passed from VAX/VMS to your 
condition handler. The mechanism-args argument is the address of the 
mechanism arguments array. 

user-action 

VMS Usage: procedure 

type: bound procedure value or procedure entry mask 

access: call after stack unwind 

mechanism: by descriptor, procedure 

User-supplied action routine that LIB$DECODE_JFAULT calls to handle the 
exception. The user-action argument is the address of a descriptor pointing 
to your user action routine. User-action may be of type "bound procedure 
value" when called by languages with up-level addressing. If user-action is 
not of type "bound procedure value," it is assumed to be the address of an 
entry mask. 
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For further information on the user action routine, see "Call Format for a User 
Action Routine" in the Description section. 


user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: by value 

Additional information passed from your handler without interpretation to 
your user action routine. The user-arg argument contains the value of this 
additional information. This is an optional argument; if omitted, zero is used. 


instruction-definitions 

VMS Usage: vector_byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Array of bytes specifying instruction opcodes and operand definitions which 
are to replace or supplement the standard instruction definitions. The 
instruction-definitions argument is the address of this array. 


If omitted, only the standard instruction definitions are used. If supplied, 
instruction-definitions is searched first, followed by the standard definitions. 

Each instruction definition consists of a series of bytes, the first one or two 
of which is the instruction opcode. If the instruction is a 2-byte opcode, the 
escape byte, which must be hex FD, FE, or FF, is placed in the first of the two 
bytes. Following the opcode may be from 0 to 16 operand definition bytes. 
These bytes indicate the operand's access type and data type. 

The end of each instruction definition is denoted by a byte containing the 
value LIB$K_DCFOPR__END (zero). The list of instruction definitions is 
terminated by two bytes, each of which contains the value -1, (hexadecimal 
FF). For further information, see "Instruction Operand Definition Codes" in 
the Description section. 


DESCRIPTION The Description section of the LIB$DECODE_FAULT routine has been 

divided into five parts. 

• Guidelines for Using LIB$DECODE_FAULT 

• Exceptions Recognized by LIB$DECODE_FAULT 

• Instruction Operand Definition Codes 

• Call Format for a User Action Routine 

• Call Format for a Signal Routine 

Guidelines for Using LIB$DECODE_FAULT 

LIB$DECODE_FAULT is a tool for building condition handlers which process 
instruction fault exceptions. Called from a condition handler, LIB$DECODE_ 
FAULT performs the following actions in this order. 

1 Unwinds intermediate stack frames back to that of the exception 

2 Decodes the instruction stream to determine the operation and its 
operands 
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3 Calls a user-supplied action routine and passes it a consistent and 
easy-to-access description of the instruction's context 

Your user action routine performs whatever tasks are necessary to handle 
the fault and returns to LIB$DECODE_FAULT. LIB$DECODE_FAULT then 
restores the context as modified by your user action routine and continues 
execution. 

Your condition handler must first decide whether or not it wishes to handle 
the exception. The signal arguments list contains the exception code and the 
address of the PC which is usually sufficient for this determination. Once 
LIB$DECODE_FAULT is called, if the exception is a fault LIB$DECODE_ 
FAULT can analyze, control does not return to the condition handler. 
Therefore, your handler must not depend on regaining control by a procedure 
return once it has called LIB$DECODE_FAULT. With your user action 
routine, LIB$DECODE_FAULT makes the original fault disappear. 

Note: Your user action routine is capable of generating a new exception, 

including one that looks identical to the original exception. Your user 
action routine may also resignal, but if the decision to resignal is made 
inside the user action routine, all post-signal stack frames are lost. 

Once your condition handler has decided that it wants to handle the 
exception, it calls LIB$DECODE_FAULT, passing as arguments the addresses 
of the signal and mechanism argument lists and a descriptor for your user 
action routine entry point. LIB$DECODE_FAULT will then perform the 
following actions: 

1 Determine if the exception is a fault it understands. If not, it returns 
SS$_RESIGNAL. 

2 Determine the context in which the exception occurred, including register 
and PSL contents, and save it. 

3 Unwind all stack frames back to that in which the exception occurred. 

4 Evaluate each operand's addressing mode, computing the resulting 
location for the operand. Immediate mode operands are expanded 
into their full form. If an invalid addressing mode is found, an SS$__ 
RADRMOD exception is generated. 

5 Unless the original exception was SS$_ACCVIO, test each operand 
for accessibility. If necessary, an access violation is signaled as if the 
instruction had tried to execute normally. See the paragraph following 
this list for more information. 

6 Unless the original exception was SS$_ROPRAND, test each floating-point 
operand which is to be read for a reserved floating operand. If necessary, 
a reserved operand fault is signaled. See the paragraph following this list 
for more information. 

7 Determine the address of the next sequential instruction. 

8 Call your user action routine with arguments as described below. 

9 Upon return from your user action routine, reflect changes to the registers 
and PSL, and continue execution at the instruction address specified by 
your user action routine. Optionally, your user action routine may resignal 
the original exception. 
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Some instructions can generate more than one fault if evaluation of one 
operand causes a fault which occurs before a later operand (which would also 
cause a fault). An example of this is the possibility that a floating-point divide 
instruction might report a divide-by-zero fault upon seeing a zero divisor 
before noticing that the dividend was a reserved operand, or was inaccessible. 

In these cases, operand-specific faults will be signaled immediately by 
LIB$DECODE_FAULT in the expectation that another condition handler (or 
the same one) can repair the situation. This may reorder the sequence of 
exceptions as seen by a program. If the operand exception is corrected, the 
original exception will reoccur, and the proper action will be taken. 

If at all possible, you should attempt to determine if a resignal is necessary 
inside the condition handler which calls LIB$DECODE_JFAULT, rather than 
inside your user action routine. The reason for this is that LIB$DECODE_ 
FAULT removes all post-signal stack frames before calling your user action 
routine. 

Your user action routine may fetch and store the operands, registers and 
PSL as is necessary for handling the exception. You should follow the 
VAX architecture rule of reading all input operands in left-to-right order, 
then writing all output operands in left-to-right order, to avoid inconsistent 
results with overlapping operands. This is especially necessary with register 
operands. 

PSL may be modified in a manner consistent with the VAX architecture. 

If the T-bit in the PSL was set at the beginning of the instruction, 
LIB$DECODE__FAULT sets the TP bit. To initiate tracing, you must set 
only the T bit. To disable tracing, you must clear both the T and TP bits. See 
the VAX-11 Architecture Reference Manual for more information. 

If the first-part-done (FPD) bit in the PSL was set when the instruction 
faulted, LIB$DECODE_FAULT only advances the PC over the instruction; 
it does not reevaluate the operands and it sets operand-count to zero. It is 
assumed that if FPD is set, the operands are in known locations (typically the 
registers). 

For the CASEB, CASEW, and CASEL instructions, only the selector, base, 
and limit operands are represented in operand-count and read-operand- 
locations. The element of registers which corresponds to the PC, described in 
the following text as R15, points to the first of the word-length displacements. 
Your user action routine must modify R15 to reflect the location of the next 
instruction to execute. 

The standard instruction definitions used by LIB$DECODE_FAULT specify 
the XFC instruction (which causes an SS$_OPCCUS fault) as having zero 
operands. You may redefine XFC if needed using the instruction-definitions 
argument to LIB$DECODE_FAULT. 

If you do not want instruction execution to resume with the next sequential 
instruction, you must modify R15 appropriately. Your user action routine 
then returns to LIB$DECODE_FAULT which restores the registers and PSL, 
and resumes instruction execution. See also LIB$_JRESTART below. 

Exceptions Recognized by LIB$DECODE_FAULT 

LIB$DECODE_FAULT recognizes the following VAX faults: 

• SS$_ACCVIO, access violation. 

• SS$_BREAK, breakpoint fault. 

• SS$__FLTDIV_F, floating divide by zero. 
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• SS$_FLTOVF_F, floating overflow. 

• SS$__FLTUND_F, floating underflow. 

• SS$_OPCCUS, opcode reserved to customers and CSS. 

• SS$_OPCDEC, opcode reserved to DIGITAL. 

• SS$_ROPRAND, reserved operand. 

• SS$_TBIT, T-bit pending trap. This is actually a fault caused by the 
TP bit being set at the beginning of instruction execution. It allows you 
to interpret all instructions by setting the PSL T-bit and allowing each 
instruction to trace-fault. 


All other exceptions, including SS$_COMPAT and SS$_RADRMOD, cause 
LIB$DECODE_FAULT to return immediately with the return status SS$_ 
RESIGNAL. 

SS$_COMPAT is generated by compatibility-mode instructions. 
LIB$DECODE_FAULT does not handle compatibility-mode instructions. 

SS$_RADRMOD is generated by a reserved addressing-mode fault. 
LIB$DECODE_FAULT assumes that all instructions follow VAX addressing¬ 
mode specifications. 


Instruction Operand Definition Codes 

Each instruction operand has an access type (read, write, ...) and a data type 
(byte, word, ...) associated with it. The operand definition codes used in both 
the instruction-definitions argument passed to LIB$DECODE—FAULT and 
in the operand-types argument passed to the user action routine encode the 
access and data types in a byte. The fields and values for operand access and 
data types are described using the following symbols. These symbols are 
defined in DIGITAL-supplied symbol definition libraries as macro or module 
name $LIBDCFDEF. 


LIB$V_DCFACC 

LIB$S_DCFACC 

LIB$M_DCFACC 


The field of the operand description code that describes the 
operand access type (bits 0:2). 

The size of the access type field (3 bits). 

The mask for the access type field. This is a 3-bit field that can 
contain any binary value from 000 through 111. The integer 
value of these bit settings defines the operand access type 
code for the LIB$M_DCFACC field. Currently, six codes are 
defined. These codes have symbolic names and are explained 
below. It is important to remember that LIB$M_DCFACC is 
NOT a bit mask. The values 0 through 6 do not refer to bits 0 
through 6. They represent the binary values 001 through 110 
as contained in the 3-bit field. 

The operand access type codes defined for the LIB$M_ 
DCFACC field are: 

LIB$K_DCFACC_R = 1 Operand is read-only 
LIB$K_DCFACC_W = 2 Operand is write-only 
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LIB$V_DCFTYP 

LIB$S_DCFTYP 

LIB$M_DCFTYP 


LIB$K_DCFACC_M = 3 
LIB$K_DCFACC_A = 4 

LIB$K_DCFACC_V = 5 

LIB$K_DCFACC_B = 6 


Operand is to be modified 

Operand is an address (must not 
be a register) 

Operand is the base of a bit field 
(same as address except that it 
may be a register) 

Operand is a branch address 


The field of the operand descriptor code which describes the 
operand data type (bits 3:7). 


The size of the operand data type field (5 bits). 


The mask for the operand data type field. This is a 5-bit 
field (bits 3:7) that can contain any binary value from 00000 
through 11111. The integer value of these bit settings 
defines the operand access type code for the LIB$M_DCFACC 
field. Currently, nine codes are defined. These codes have 
symbolic names and are explained below. It is important to 
remember that LIB$M_DCFTYP is NOT a bit mask. The values 
0 through 9 do not refer to bits 0 through 9. They represent 
the binary values 00001 through 01001 as contained in the 
5-bit field. The operand access type codes defined for the 
LIB$V_DCFTYP field are: 


LIB$K_DCFTYP_B = 1 
LIB$K_DCFTYP_W = 2 
LIB$K_DCFTYP_L = 3 
LIB$K_DCFTYP_Q = 4 
LIB$K_DCFTYP_0 = 5 
LIB$K_DCFTYP_F = 6 
LIB$K_DCFTYP_D = 7 
LIB$K_DCFTYP_G = 8 
LIB$K_DCFTYP_H = 9 


Operand is a byte 
Operand is a word 
Operand is a longword 
Operand is a quadword 
Operand is an octaword 
Operand is an F_floating 
Operand is a D_floating 
Operand is a G_floating 
Operand is an H_floating 


Symbols of the form LIB$K_DCFOPR_xy, where x is the access type and y is 
the data type, are also defined. These combine the notions of access and data 
type. For example, LIB$K_DCFOPR_MF has the following value: 

51 ( 3 +( 6 * 8 )) 

It denotes modify access of an F_floating item. For the branch access type, 
only the types BB, BW, and BL are defined; otherwise, all combinations are 
available. 


Call Format for a User Action Routine 

LIB$DECODE_FAULT calls the user action routine when it finds an exception 
to be handled. Your user action routine handles the exception in any manner 
that you specify and then returns to LIB$DECODE_FAULT. 

action-routine opcode ,instr-PC ,PSL .registers ,operand-count 

,operand-types ,read-operand-locations 
,write-operand-locations .signal-args 
,signal-routine .context ,user-arg 
,original-registers 
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opcode 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Opcode of the instruction which caused the fault. The opcode argument 
is the address of a longword which contains this opcode. LIB$DECODE_ 
FAULT supplies this opcode when it calls the user action routine. 


For 2-byte opcodes, the escape code (for example, hex FD) is in the low-order 
byte. You must use this argument to examine the opcode instead of reading 
the bytes pointed to by instr-PC. This is because if a debugger breakpoint 
has been set on the instruction, only opcode contains the original instruction. 


instr-PC 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Value of the PC for the instruction that caused the fault. The instr-PC 
argument is the address of a longword which contains the PC value. 


Note the difference between this value and the contents of the registers array 
element which corresponds to the PC. R15 of the registers array element 
contains the address of the byte after the instruction which caused the fault. 


PSL 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Processor status longword (PSL) at the time of the fault. The PSL argument 
is the address of a longword that contains this PSL. Your user action routine 
may modify this PSL within the restrictions of the VAX architecture. 


registers 

VMS Usage: vector—longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference, array reference 

Contents of registers RO through R15 (PC) at the time of the fault, but after 
operand addressing-mode processing. This includes any autoincrements 
and/or autodecrements. The registers argument is the address of this 16- 
longword array. Each longword of the registers array contains the contents of 
one register. 

Your user action routine may modify these values. If it does, the new values 
will be reflected when instruction execution continues. 


R15 denotes the 16th longword in the registers array, which corresponds 
to the PC. R15 contains the address of the next byte after the current 
instruction. Unless this value is modified by your user action routine, 
instruction execution will resume at that address. An exception is for the 
CASEB, CASEW, and CASEL instructions; R15 contains the address of the 
first displacement word. For these instructions, your user action routine must 
modify R15 to point to the next instruction to execute. 
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Upon instruction completion, registers R0-R15 are restored from this array. 
However, if signal-routine is used to cause a fault or if instruction restart is 
specified by returning LIB$_RESTART, original-registers is used instead. 


operand-count 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of operands in the instruction currently being decoded. The 
operand-count is the address of a longword which contains this number. 


operand-types 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference,array reference 

Array of longwords, one element for each operand, which contain the type 
codes for the associated operand. The operand-types argument is the address 
of this array. 


The operand type codes are further defined under "Instruction Operand 
Definition Codes," which appeared above in this Description section. 


read-operand-locations 

VMS Usage: vector_longword_unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Array of longwords, one element for each operand, which contains the 
addresses of the operands to be read. The read-operand-locations argument 
is the address of this array. 


The address given in the array may not be the actual address of the operand if 
the operand is not a memory location. If the operand is a register, the address 
indicates a copy of the register value(s) at the time of operand evaluation. 

If the operand access type is ADDRESS or FIELD, and the operand is not a 
register, the address is the address of the item. If the operand access type 
is FIELD and the operand is a register, the address refers to the appropriate 
element in the registers array. If the operand access type is BRANCH, the 
address is the destination PC of the branch. For WRITE access operands, the 
address value is zero. 


write-operand-locations 

VMS Usage: longword—unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Array of longwords, one element for each operand, which contains the 
addresses of operands which are to be written. The write-operand-locations 
argument is the address of this array. If the operand access type is not 
MODIFY, WRITE, ADDRESS, or FIELD, the pointer value is zero. 
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signal-args 

VMS Usage: vector_longword-unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Signal arguments list of the original exception, as passed from VAX/VMS to 
your condition handler and then to LIB$DECODE_FAULT. The signal-args 
argument is the address of an array of longwords that contains these signal 
arguments. 

signal-routine 

VMS Usage: mask—longword 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

Entry mask of a routine which your user action routine must call if it wishes 
to report an exception for the instruction that faulted. The signal-routine 
argument is the address of this entry mask. 

For further information, see "Call Format for a Signal Routine" in the 
Description section. 


context 

VMS Usage: context 
type: unspecified 

access: read only 

mechanism: by value 

Context in which the exception occurs, including the register and PSL 
contents, to be used when calling the signal-routine. The context argument 
contains the value of this context. 


user-arg 

VMS Usage: user—arg 
type: unspecified 

access: read only 

mechanism: by value 

Optional argument passed to LIB$DECODE—FAULT. If the argument was not 
specified, the value zero is substituted. The user-arg argument contains the 
value of this optional argument. 


original-registers 

VMS Usage: vector.longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference, array reference 

Array containing the values of registers RO through R15 (PC) at the time of 
the fault, before operand processing. The original-registers argument is the 
address of this 16-longword array. 


If the action routine specifies that the instruction should restart or that a fault 
should be generated, the registers are restored from original-registers. See 
also the description of registers above. 
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Condition Values Returned from the User Action Routine 

The user action routine can return the following condition values to 
LIB$DECODE_FAULT. 


Condition Value 

Description 

SS$_CONTINUE 

If the user action routine returns a value of SS$_ 
CONTINUE, instruction execution will continue as specified 
by the current contents of the registers element for the 

PC. 

SS$_RESIGNAL 

If it returns SS$_RESIGNAL, the original exception is 
resignaled, with the only changes reflected being those 
specified by registers elements for RO and R1 (which are 
stored in the mechanism arguments vector), PC, and PSL. 
All other registers are restored from original registers. 

LIB$_RESTART 

If the user action routine returns LIB$_RESTART, the 
current instruction is restarted with registers restored from 
original-registers and a PSL from PSL. This feature is 
useful for writing trace handlers. 


Call Format for a Signal Routine 


Your action routine calls the signal routine using this format: 

sign&l-routin* fault-flag ,context ,signal-args 

fault-flag 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword flag whose low-order bit determines whether or not the exception 
is to be signaled as a fault or as a trap. The fault-flag argument contains the 
address of this longword. 


If the low-order bit of fault-flag is set to 1, the exception is signaled as a 
fault. If the low-order bit of fault-flag is set to 0, the exception is signaled as 
a trap; the current contents of the registers array are used. In either case, the 
current contents of PSL are used to set the exception PSL. 


context 


VMS Usage: context 
type: unspecified 

access: read only 

mechanism: by reference 

Context in which the new exception is to occur, as passed to your user-action 
routine by LIB$DECODE_FAULT. The context argument is the address of 


this context value. 
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signal-args 

VMS Usage: arg_list 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Signal arguments to be used. The signal-args argument is the address of an 
array of longwords which contains these signal arguments. 


The first longword contains the number of following longwords; the 
remainder of the list contains signal names and arguments. Unlike the 
signal argument list passed to a condition handler, no PC or PSL is present. 


Before the exception is signaled, the stack frames are unwound back to the 
original exception. You should be careful when causing a new signal that 
a loop of faults is not inadvertently generated. For example, the condition 
handler which called LIB$DECODE_JFAULT will usually be called for the 
second signal. If the handler does not analyze the second signal as such, it 
may cycle through the identical path as for the first signal. 


To resignal the current exception, have the user action routine return a value 
of SS$_RESIGNAL instead of calling the signal routine (unless you wish 
previously called condition handlers to be called again). 


CONDITION 

VALUES 

RETURNED 

SS$_RESIGNAL 

Resignal condition to next handler. The exception 
described by signal-args was not an instruction 
fault handled by LIB$DECODE_FAULT. If 
LIB$DECODE_FAULT can process the fault, it 
does not return to its caller. 

CONDITION 

VALUE 

SIGNALED 

LIB$_INVARG 

Invalid argument to Run-Time Library. The 
instruction definition contained more than 16 
operands or an operand definition contained an 
invalid data type or access code. This message is 
signaled after the stack frames have been unwound 
so that it appears to have been signaled from a 
procedure which was called by the instruction 
which faulted. 


EXAMPLE 


C+ 

C Example condition handler and user-action procedure using 
C LIB$DECODE_FAULT. This example demonstrates the use of 
C most of the features of LIB#DECODE_FAULT. Its purpose 
C is to handle floating underflow and overflow faults, 

C replacing the result of the instruction with the correctly 
C signed smallest possible value for underflows, or greatest 
C possible value for overflows. 

C 

C For simplicity, faults involving the POLYx instructions are 
C not handled. 

C 

C*** 

C FIXUP_RESULT is the condition handler enabled by the program 
C desiring the fixup of overflows and underflows. 

C*** 

C- 
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INTEGER*4 FUNCTION FIXUP.RESULT(SIGARGS, MECHARGS) 


IMPLICIT NONE 
INCLUDE '($SSDEF) 1 
INCLUDE '(ILIBDCFDEF)' 
INTEGER*4 SIGARGS(1:*) 
INTEGERS MECHARGS(1: *) 


! SS$_ symbols 
! LIBIDECODE.FAULT symbols 
! Signal arguments list 
! Mechanism arguments list 


C+ 

C This is a sample redefinition of MULH3 instruction. 
C- 



C+ 

C 

C- 


BYTE 0PTABLE(8) 
1 
2 

3 

4 

5 


/'FD'X,'85'X, 
LIB$K_DCFOPR_RH, 
LIB$K_DCFOPR_RH, 
LIB$K_DCFOPR_WH, 
LIBlK.DCFOPR.END, 
•FF'X,'FF 1 X/ 


! MULH3 opcode 
! Read H.floating 
! Read H.floating 
! Write H.floating 
! End of operands 
! End of instructions 


INTEGER*4 LIB$DECODE_FAULT ! External function 

EXTERNAL FIXUP.ACTION ! Action routine to do the fixup 


Determine if the exception is one we wish to handle. 


C+ 

C 

C 

C 

C- 



C+ 

C 

C 

C- 


IF ((SIGARGS(2) .EQ. SSl.FLTOVF.F) .OR. 

1 (SIGARGS(2) .EQ. SSS.FLTUND.F)) THEN 

We think we can handle the fault. Call 
LIB$DECODE_FAULT and pass it the signal arguments and 
the address of our action routine and opcode table. 

FIXUP.RESULT = LIB$DECODE_FAULT (SIGARGS, 

1 MECHARGS, %DESCR(FIXUP.ACTION),, OPTABLE) 

RETURN 
END IF 


We can only get here if we couldn't handle the fault. 
Resignal the exception. 


FIXUP.RESULT = SS$_RESIGNAL 

RETURN 

END 



C+ 

C 

C- 


User action routine to handle the fault. 


INTEGER*4 FUNCTION FIXUP.ACTION 
1 
2 

3 

4 

5 


(OPCODE.INSTR.PC,PSL, 
REGISTERS,OP.COUNT, 
OP_TYPES.READ.OPS, 
WRITE.OPS,SIGARGS. 
SIGNAL.ROUT,CONTEXT. 
USER_ARG.ORIG.REGS) 


IMPLICIT NONE 
INCLUDE '($SSDEF)' 
INCLUDE '($PSLDEF)' 
INCLUDE '($LIBDCFDEF)' 


INTEGER*4 OPCODE 
INTEGER*4 INSTR.PC 
INTEGER*4 PSL 



INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 
INTEGER*4 


REGISTERS(0:15) 
OP.COUNT 
0P_TYPES(i:*) 
READ_0PS(1:*) 
WRITE.OPS(1:*) 
SIGARGS(1:*) 
SIGNAL.ROUT 
CONTEXT 
USER.ARG 
ORIG.REGS(0:15) 


SS$_ definitions 
PSL$ definitions 
LIB$DECODE_FAULT 
definitions 

Instruction opcode 
PC of this instruction 
Processor status 
longword 
R0-R15 contents 
Number of operands 
Types of operands 
Addresses of read operands 
Addresses of write operands 
Signal argument list 
Signal routine address 
Signal routine context 
User argument value 
Original registers 
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C+ 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C 

C- 


C+ 

C 

C 

C 

C- 


C+ 

C 

C 

c 

c 

c 

c 

c 

c 


Declare and initialize table of class codes for each of the 
"real" opcodes. We'll index into this by the first byte of 
one-byte opcodes, the second byte of two-byte opcodes. The 
class codes will be used in a computed GOTO (CASE). The 
codes are: 

0 - Unsupported 

1 - ADD 

2 - SUB 

3 - MUL.DIV 

4 - ACB 

5 - CVT 

6 - EMOD 


The class mainly determines how we compute the 
result, except for ACB. 

sign of 

the 

BYTE 

INST_CLASS_TABLE(0:255) 



DATA 

INST.CLASS.TABLE / 



1 

48*0, 

j 

00-2F 

2 

0,0,0.5.0.0.0,0,0.0,0,0,0,0,0,0, 

i 

30-3F 

3 

1.1.2.2,3.3,3,3,0.0,0,0,0.0.0.4, 

j 

40-4F 

4 

0,0,0,0,6,0,0,0,0,0,0,0.0,0,0,0, 

j 

50-5F 

5 

1,1,2.2,3.3.3,3.0.0,0,0,0,0,0.4, 

i 

60-6F 

6 

0,0,0.0,6.0.5.0.0.0.0.0.0,0,0,0, 

i 

70-7F 

7 

112*0, 

i 

80-EF 

8 

0,0,0.0.0.0,5.5,0,0,0.0,0,0,0.0/ 

| 

F0-FF 


Table of operand sizes in 8-bit bytes, indexed by the 
datatype code contained in the OP_TYPES array. Only floating 
types matter. 


BYTE 0P_SIZES(9) /0.0.0,0,0,4.8,8,16/ 


INTEGER*4 LIBlEXTV 

! External function 

INTEGER*4 RESULT.NEGATIVE 

! -1 if result negative. 

INTEGER*4 SIGN1,SIGN2,SIGN3 

! 0 if positive 
! Signs of operands 

INTEGER*4 INST.BYTE 

! Current opcode byte 

INTEGER*4 INST.CLASS 

! Class of instruction 

INTEGER*4 OP.DTYPE 

! from table 
! Datatype of operand 

INTEGER*4 OP.SIZE 

! Size of operand in 

INTEGER*4 RESULT.OP 

! 8-bit bytes 
! Position of result 

LOGICAL+4 OVERFLOW 

! in WRITE.OPS array 
! TRUE if SS$_FLTOVF_F 

L0GICAL*4 SMALLER 

! Function which 

PARAMETER ESCD = 'OFD'X 

! compares operands 
! First byte of G,H instructions 

INTEGER*2 SMALL_F(2) 

! Smallest F_floating 

DATA SMALL.F /'0080'X,0/ 
INTEGER*2 SMALL_D(4) 

! Smallest D_floating 

DATA SMALL.D /'0080'X,0,0,0/ 
INTEGER*2 SMALL_G(4) 

! Smallest G.floating 

DATA SMALL.G /'0010'X,0,0,0/ 
INTEGER*2 SMALL_H(8) 

! Smallest H_floating 


DATA SMALL.H /'0001'X,0.0,0.0,0,0,0/ 

INTEGER*2 BIGGEST(8) ! Biggest value (all datatypes) 

DATA BIGGEST /'7FFF'X,7*'FFFF'X/ 

INTEGERS SIGNAL_ARRAY(2) ! Array for signalling new 

! exception 


NOTE: Because the operands arrays contain the locations of 

the operands, rather than the operands themselves, 
we must call a procedure using the 7,VAL function to 
"fool" the called procedure into considering the 
contents of an operands array element as the address 
of an item. This would not be necessary in a 
language that understood the concept of pointer 
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C variables, such as PASCAL. 

C 
C 

C If FPD is set in the PSL, signal SS$_ROPRAND (reserved operand). In 
C reality this shouldn't happen since none of the instructions we 
C handle can set FPD, but do it as an example. 

C- 

IF (BTEST(PSL,PSL$V_FPD)) THEN 
SIGNAL_ARRAY(1) = 1 
SIGNAL_ARRAY(2) = SS$_ROPRAND 
CALL SIGNAL.ROUT ( 

1 1. 

2 SIGNAL.ARRAY, 

3 CONTEXT) 

END IF 
C+ 

C Set OVERFLOW according to the exception type. We assume that 
C the only alternatives are SS$_FLTOVF_F and SS$_FLTUND_F. 

C- 

OVERFLOW = (SIGARGS(2) .EQ. SS$_FLTOVF_F) 

C+ 

C Determine the datatype of the instruction by that of its 
C second operand, since that is always the type of the 
C destination. 

C- 

OP.DTYPE = IBITS(OP_TYPES(2),LIB$V_DCFTYP,LIB$S_DCFTYP) 

C+ 

C Get the size of the datatype in words. 

C- 

OP.SIZE = OP.SIZES (OP.DTYPE) 

C+ 

C Determine the class of instruction and dispatch to the 
C appropriate routine. 

C- 

INST.BYTE = IBITS(OPCODE,0.8) ! Get first byte 

IF (INST.BYTE .EQ. ESCD) INST.BYTE * IBITS(OPCODE,8,8) 

INST.CLASS = INST_CLASS_TABLE(INST.BYTE) 

GO TO (1000,2000,3000,4000,5000,6000),INST.CLASS 

C+ 

C If we get here, the instruction's entry in the 

C INST.CLASS.TABLE is zero. This might happen if the instruction was 
C a POLYx, or was some other unsupported instruction. Resignal the 
C original exception. 

C- 

FIXUP.ACTION = SS$_RESIGNAL ! Resignal condition to next handler 
RETURN ! Return to LIB$DECODE_FAULT 

C+ 

C 1000 - ADDF2, ADDF3, ADDD2, ADDD3, ADDG2, ADDG3, ADDH2, ADDH3 
C 

C Result's sign is the same as that of the first operand, 

C unless this is an underflow, in which case the magnitudes of 
C the values may change the sign. 

C- 

1000 RESULT.NEGATIVE = LIB$EXTV (15,1,7.VAL(READ_0PS(1))) 

IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(OP_SIZE,y.VAL(READ_OPS(l)) , 

1 */,VAL (READ.OPS (2) ) ) ) 

2 RESULT.NEGATIVE = .NOT. RESULT.NEGATIVE 
END IF 

GO TO 9000 

C+ 

C 2000 - SUBF2, SUBF3, SUBD2, SUBD3, SUBG2, SUBG3, SUBH2, SUBH3 
C 

C Result's sign is the opposite of that of the first operand, 

C unless this is an underflow, in which case the magnitudes of 
C the values may change the sign. 


! Count of signal arguments 
! Error status value 

! Fault flag - signal as fault 
! Signal arguments array 
! Context as passed to us 
! Call will never return 
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c- 

2000 RESULT.NEGATIVE = .NOT. LIB$EXTV (15.1.7.VAL (READ.OPS (1))) 

IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(0P_SIZE,7.VAL(READ_0PS(1)) . 

1 7.VAL (READ.OPS(2) ) ) ) 

2 RESULT.NEGATIVE = .NOT. RESULT.NEGATIVE 
END IF 

GO TO 9000 

C+ 

C 3000 - MULF2, MULF3, MULD2, MULD3, MULG2, MULG3, MULH2, MULH3, 

C DIVF2, DIVF3. DIVD2, DIVD3, DIVG2, DIVG3, DIVH2, DIVH3, 

C 

C If the signs of the first two operands sire the same, then the 
C result's sign is positive, if they are not it is negative. 

C- 

3000 SIGN1 = LIBIEXTV (15,1.7.VAL (READ.OPS (1) ) ) 

SIGN2 = LIBIEXTV (15,1,7.VAL(READ.OPS(2))) 

RESULT.NEGATIVE * SIGN1 .XOR. SIGN2 
GOTO 9000 

C+ 

C 4000 - ACBF, ACBD, ACBG, ACBH 
C 

C The result's sign is the same as that of the second operand 
C (addend), unless this is underflow, in which case the 
C magnitudes of the addend and index may change the sign. 

C We must also determine if the branch is to be taken. 

C- 

4000 SIGN2 * LIBIEXTV (15.1,7.VAL(READ.OPS(2))) 

RESULT.NEGATIVE * SIGN2 
IF (.NOT. OVERFLOW) THEN 

IF (SMALLER(OP_SIZE,%VAL(READ.OPS(2)), 

1 7.VAL (READ.OPS (3) ) ) ) 

2 RESULT.NEGATIVE = .NOT. RESULT.NEGATIVE 
END IF 

O 

C If this is overflow, then the branch is not taken, since the 
C result is always going to be greater or equal in magnitude 
C to the limit, and will be the correct sign. If underflow, 

C the branch is ALMOST always taken. The only case where the 
C branch might not be taken is when the result is exactly 
C equal to the limit. For this example, we are going to ignore 
C this exceptional case. 

C- 

IF (.NOT. OVERFLOW) 

1 REGISTERS(15) = READ.OPS(4) ! Branch destination 

GO TO 9000 

C+ 

C 5000 - CVTDF, CVTGF, CVTHF, CVTHD, CVTHG 
C 

C Result's sign is the same as that of the first operand. 

C- 

5000 RESULT.NEGATIVE = LIBIEXTV (15,1,7.VAL(READ.OPS(1))) 

GO TO 9000 

C+ 

C 6000 - EMODF, EMODD, EMODG, EMODH 
C 

C If the signs of the first and third operands are the same, then the 
C result's sign is positive, else it is negative. 

C- 

6000 SIGN1 = LIBIEXTV (15,1,7.VAL (READ.OPS (1) ) ) 

SIGN2 = LIBIEXTV (15,1,7.VAL (READ.OPS (3) ) ) 

RESULT.NEGATIVE = SIGN1 .XOR. SIGN2 
GOTO 9000 

C+ 

C All code paths merge here to store the result value. We also 
C set the PSL appropriately. First, determine which operand is 
C the result. 

C- 
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9000 RESULT.OP = OP.COUNT 
IF (INST.CLASS .EQ. 4) 

1 RESULT.OP = RESULT.OP - 1 ! ACBx 

C+ 

C Select result based on datatype and exception type. 

C- 

IF (OVERFLOW) THEN 

CALL LIBIM0VC3 (OP_SIZE,BIGGEST, y,VAL(WRITE.OPS(RESULT.OP) ) ) 
ELSE 

GO TO (9100,9200,9300,9400), OP.DTYPE-(LIBlK.DCFTYP.F-l) 

C+ 

C Should never get here. Resignal original exception. 

C- 

FIXUP.ACTION = SS$_RESIGNAL 
RETURN 

C+ 

C 9100 - F.floating result 
C- 

9100 CALL LIB$M0VC3 ( OP.SIZE. SMALL_F,y.VAL (WRITE.OPS (RESULT.OP))) 

GOTO 9500 

C+ 

C 9200 - D.floating result 
C- 

9200 CALL LIB$M0VC3 (OP.SIZE, SMALL.D, y,VAL(WRITE.OPS(RESULT.OP) ) ) 

GOTO 9500 

C+ 

C 9300 - G.floating result 
C- 

9300 CALL LIB$M0VC3 (OP.SIZE.SMALL.G,XVAL(WRITE.OPS(RESULT.OP))) 

GOTO 9500 

C+ 

C 9400 - H.floating result 
C- 

9400 CALL LIB$M0VC3 (OP.SIZE,SMALL.H,%VAL(WRITE.OPS(RESULT.OP))) 

GOTO 9500 

9500 END IF 


C+ 

C Modify the PSL to reflect the stored result. If the result was 
C negative, set the N bit. Clear the V (overflow) and Z (zero) bits. 
C If the instruction was an ACBx, leave the C (carry) bit unchanged, 

C otherwise clear it. 

C- 


IF (RESULT.NEGATIVE) THEN 
PSL * IBSET (PSL.PSLIV.N) 
ELSE 

PSL = IBCLR (PSL.PSLIV.N) 
END IF 

PSL = IBCLR (PSL,PSLIV.V) 

PSL = IBCLR (PSL,PSL|V_Z) 

IF (INST.CLASS .NE. 4) 

1 PSL = IBCLR (PSL,PSL$V_C) 


! Set N bit 

! Clear N bit 

! Clear V bit 
! Clear Z bit 

! Clear C bit if not ACBx 


C+ 

C Set the sign of result. 
C- 


IF (RESULT.NEGATIVE) 

1 CALL LIBIINSV (1,15,1, y.VAL (WRITE.OPS (RESULT.OP) ) ) 
C+ 

C Fixup is complete. Return to LIBlDECODE.FAULT. 

C- 


FIXUP.ACTION = SSI.CONTINUE 

RETURN 

END 


C+ 

C Function which compares two floating values. It returns .TRUE, if 
C the first argument is smaller in magnitude than the second. 
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c- 

LOGICAL+4 FUNCTION SMALLER(NBYTES,VAL1,VAL2) 

INTEGER*4 NBYTES ! Number of bytes in values 

INTEGER*2 VAL1(*),VAL2(*) ! Floating values to compare 

INTEGERS WORD A, WORDB 

SMALLER = .TRUE. ! Initially return true 

C+ 

C Zero extend to a longword for unsigned compares. 

C Compare first word without sign bit. 

C- 


WORDA = IBCLR(ZEXT(VAL1(1)),15) 

WORDB = IBCLR(ZEXT(VAL2(1)),15) 

IF (WORDA .LT. WORDB) RETURN 

DO 1*2,NBYTES/2 
WORDA * ZEXT(VALKI)) 

WORDB * ZEXT(VAL2(I)) 

IF (WORDA .LT. WORDB) RETURN 
END DO 

SMALLER = .FALSE. ! VAL1 not smaller than VAL2 

RETURN 

END 


This FORTRAN example implements a simple recovery scheme for floating 
underflow and overflow faults, replacing the result of the instruction with 
the correctly signed smallest possible value for underflows or largest possible 
value for overflows. 
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LIB$DEC_ 

OVER—Enable or Disable 

Decimal Overflow 
Detection 


LIB$DEC_OVER enables or disables decimal overflow detection for 
the calling procedure activation. The previous decimal overflow 
setting is returned. 

FORMAT 

LIB$DEC_OVER new-setting 

RETURNS 

VMS Usage: longword—unsigned 
type: longword integer (unsigned) 

access: write only 

mechanism: by value 

The old decimal overflow enable setting (the previous contents of SF$W_ 
PSW[PSW$V_DV] in the caller's frame). 

ARGUMENT 

new-setting 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

New decimal overflow enable setting. The new-setting argument is the 
address of an unsigned byte that contains the new decimal overflow enable 
setting. Bit 0 set to 1 means enable; bit 0 set to 0 means disable. 

DESCRIPTION 

The caller's stack frame will be modified by this procedure. 

A call to LIB$DEC_OVER affects only the current procedure activation and 
does not affect any of its callers or any procedures that it may call. However, 
the setting does remain in effect for any procedures which are subsequently 
entered through a JSB entry point. 

EXAMPLE 


DECOVF: PROCEDURE OPTIONS (MAIN); 

DECLARE LIB$DEC_OVER ENTRY (FIXED BINARY (7)) /* Address of byte for 

/* enable/disable 
/* setting */ 

RETURNS (FIXED BINARY (31)); /* Old setting 

*/ 


DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY; 

DECLARE RESULT FIXED BINARY (31); 

DECLARE (A.B) FIXED DECIMAL (4,2); 

ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); 

RESULT = LIB$DEC_OVER (DISABLE); /* Disable recognition of decimal 

/* overflow in this block */ 
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A = 99.99; 

B ® A + 2; 

PUT SKIP LIST ('In MAIN'); 

BEGIN; 

B = A + 2; 

PUT LIST ('In BEGIN block'); 
CALL Q; 

Q: PROCEDURE; 

B = A + 2; 

PUT LIST ('In Q'); 
END Q; 

END /* Begin */; 

END DECOVF; 


This PL/I program shows how to use LIB$DEC_OVER to enable or disable 
the detection of decimal overflow. Note that in PL/I, disabling decimal 
overflow using this routine only causes the condition to be disabled in the 
current block; descendent blocks will have the condition enabled unless this 
routine is called in each block. 
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LIB$DELETE_FILE—Delete One Or More 

Files 


LIB$DELETE_FILE deletes one or more files. The specification of the 
file(s) to be deleted may include wildcards. 

LIB$DELETE_FILE is similar in function to the DCL command 
DELETE. 

FORMAT 

LIB$DELETE_FILE filespec[,default-filespec] 

[, related-filespec] 

[, success-routine] 

[,error-routine] 

[, confirm-routine] [, user-arg] 
[,resultant-name] 

[, file-scan-context] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the Record Management Services (RMS) file specification of 
the file(s) to be deleted. The filespec argument is the address of a descriptor 
pointing to the file specification. If the specification includes wildcards, each 
file that matches the specification is deleted. The string must not contain 
more than 255 characters. Any string class is supported. 


default-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Default file specification of the file(s) to be deleted. The default-filespec 
argument is the address of a descriptor pointing to the default file 
specification. This is an optional argument; if omitted, the default is the 
null string. Any string class is supported. 

See the VAX Record Management Services Reference Manual for information on 
default file specifications. 
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related- filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Related file specification of the file(s) to be deleted. The related-filespec 
argument is the address of a descriptor pointing to the related file 
specification. Any string class is supported. This is an optional argument; if 
omitted, the default is the null string. 


Input file parsing is used. See the VAX Record Management Services Reference 
Manual for information on related file specifications and input file parsing. 


The related file specification is useful when you are processing lists of file 
specifications. Unspecified portions of the file specification are inherited from 
the last file processed. 


success-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied success routine that LIB$DELETE_FILE calls after it 
successfully deletes a file. The success-routine argument is the address 
of the entry mask of the success routine. 


The success routine can be used to display a log of the files that were deleted. 
For more information on the success routine, look under "Call Format for a 
Success Routine" in the Description section. 


error-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied error routine that LIB$DELETE_FILE calls when it detects an 
error. The error-routine argument is the address of the entry mask of this 
routine. 


The error routine returns a success/fail value which LIB$DELETE_FILE uses 
to determine if more files should be processed. For more information on 
the error routine, see "Call Format for an Error Routine" in the Description 
section. 


confirm-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied confirm routine that LIB$DELETE_FILE calls before each file is 
deleted. The confirm-routine argument is the address of the entry mask of 
this routine. The value returned by the confirm routine determines whether 
or not the file will be deleted. The confirm routine can be used to select 
specific files for deletion based on criteria such as expiration date, size, and so 
on. 
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user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

User-supplied argument that LIB$DELETE_FILE passes to the error, success 
and confirm routines each time they are called. Whatever mechanism is also 
used to pass user-arg to LIB$DELETE_FILE is used to pass it to the routines. 
This is an optional argument; if omitted, zero is passed by value. 


resultant-name 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which LIB$DELETE_FILE writes the RMS resultant file 
specification of the last file processed. The resultant-name argument is 
the address of a descriptor pointing to the resultant name. 


If present, resultant-name is used to store the file specification passed to the 
user-supplied routines, instead of a default class S, type T string. Therefore, 
this argument should be specified when the user-supplied routines are used 
and those routines require a descriptor type other than class S, type T. Any 
string class is supported. 


file-scan-context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Context for deleting a list of filespecs. The file-scan-context argument is the 
address of a longword containing the context value. 


You must initialize the file scan context to zero before the first of a series of 
calls to LIB$DELETE_FILE. LIB$FILE_SCAN uses this context to retain the 
file context for multiple input files. You must specify this context only when 
you are dealing with multiple input files, as the DCL command DELETE 
does. You may deallocate the context allocated by LIB$FILE_SCAN by 
calling LIB$FILE_SCAN_END after all calls to LIB$DELETE_FILE have been 
completed. 


DESCRIPTION This Description section is divided into three parts. 

• Call Format for a Success Routine 

• Call Format for an Error Routine 

• Call Format for a Confirm Routine 

Call Format for a Success Routine 

The success routine is called only if the success-routine argument was 
specified in the LIB$DELETE_FILE argument list. 

The calling format of a success routine is as follows: 

success-routine lilespec [,user-arg] 
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filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Record Management Services (RMS) resultant file specification of the file 
being deleted. The filespec argument is the address of a descriptor pointing 
to the file specification. If the resultant-name argument was specified, it is 
used to pass the string to the success routine. Otherwise, a class S, type T 
string is passed. Any string class is supported. 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value of user-arg passed by LIB$DELETE_FILE to the success routine. The 
same passing mechanism that was used to pass user-arg to LIB$DELETE_ 
FILE is used by LIB$DELETE_FILE to pass user-arg to the success routine. 
This is an optional argument. 

Call Format for an Error Routine 

The error routine is called only if the error-routine argument was specified in 
the LIB$DELETE_FILE argument list. 

The calling format of an error routine is as follows: 

•rror-routin* filespec .rms-sts ,rms-stv .error-source [.user-arg] 

filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String containing the RMS resultant file specification of the file being deleted. 
If resultant-name was specified, it is used to pass the string to the error 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 

rms-sts 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Primary condition code (FAB$L_STS) which describes the error that occurred. 
The rms-sts argument is the address of an unsigned longword that contains 
the primary condition code. 


rms-stv 

VMS Usage: cond—value 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Secondary condition code (FAB$L_STV) which describes the error that 
occurred. The rms-stv argument is the address of an unsigned longword that 
contains the secondary condition code. 
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error-source 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Integer code that indicates the point at which the error was found. The 
error-source argument is the address of a longword integer containing the 
code of the error source. 

Possible values for the error code are as follows: 

0 Error searching for filespec 
1 Error deleting file 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value passed to LIB$DELETE_FILE that is then passed to error-routine using 
the same passing mechanism that was used to pass it to LIB$DELETE_FILE. 
This is an optional argument. 

If the error routine returns a success status (bit 0 set), then LIB$DELETE_FILE 
will continue processing files. If a failure status (bit 0 clear) is returned, then 
processing will cease immediately and LIB$DELETE_FILE will return with 
the error status. 

If the error-routine argument is not specified, LIB$DELETE_FILE will return 
to its caller the most severe error status encountered while deleting the 
files. If the error routine is called for an error, the success status LIB$_ 
ERRROUCAL is returned. 

The error routine is not called for errors related to string copying. 

Call Format for a Confirm Routine 

The confirm routine is called only if the confirm-routine argument was 
specified in the call to LIB$DELETE_EILE. 

The calling format of the confirm routine is as follows: 

confirm-routine filespec ,fab [.user-arg] 


filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

RMS resultant file specification of the file to be deleted. The filespec 
argument is the address of a descriptor pointing to the file specification. 

If resultant-name was specified, it is used to pass the string to the confirm 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 
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fab 

VMS Usage: fab 
type: unspecified 

access: read only 

mechanism: by reference 

RMS FAB that describes the file being deleted. Your program may perform 
an RMS $OPEN on the FAB to obtain file attributes to determine whether the 
file should be deleted, but must close the file with $CLOSE before returning 
to LIB$DELETE_FILE. 


user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

The value of user-arg that LIB$DELETE_FILE passes to the confirm routine 
using the same passing mechanism that was used to pass it to LIB$DELETE_ 
FILE. This is an optional argument. 


If confirm routine returns a success status (bit 0 set), the file is then deleted; 
otherwise, the file is not deleted. 


CONDITION SS$_NORMAL 

VALUES LIB$_ERRROUCAL 

RETURNED 

LIB$_INVFILSPE 

LIB$_INVSTRDES 

LIB$_WRONUMARG 


Routine successfully completed. 

Success, but an error routine was called. A file 
error was encountered but the error routine was 
called to handle the condition. 

Invalid file specification. Filespec or default- 
filespec is longer than 255 characters. 

Invalid string descriptor. The descriptor for a string 
argument was not a valid string descriptor. 

Wrong number of arguments. An incorrect number 
of arguments was passed to LIB$DELETE_FILE. 


Any condition value returned by LIB$SCOPY_xxx except those condition 
values specifying truncation errors. 

Any condition value returned by RMS. If error-routine is not specified, this is 
the most severe of the RMS errors encountered while deleting the files. 


EXAMPLE 


PROGRAM DELETE_EXAMPLE(INPUT, OUTPUT); 

<♦> 

{ Declare external function LIB$DELETE_FILE. Throughout this 
{ example, the user-arg argument is not used. 

{-> 

FUNCTION LIB$DELETE_FILE( 

FILESPEC: VARYING [A] OF CHAR; 

DEFAULT.FILESPEC: VARYING [B] OF CHAR; 

REL.FILESPEC : VARYING [D] OF CHAR; 

%IMMED [UNBOUND] PROCEDURE SUCCESS.ROUTINE 

(FILESPEC : VARYING [A] OF CHAR) := '/.IMMED 0; 

'/.IMMED [UNBOUND] FUNCTION ERROR.ROUTINE 

(FILESPEC : VARYING [A] OF CHAR; RMS.STS, RMS.STV : INTEGER) 
: BOOLEAN := '/.IMMED 0; 

RIMMED [UNBOUND] FUNCTION CONFIRM.ROUTINE 
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(FILESPEC: VARYING [A] OF CHAR): BOOLEAN := 7.IMMED 0; 
VAR USER.ARG : [UNSAFE] INTEGER := ‘/.IMMED 0; 

VAR RESULT.NAME : VARYING [C] OF CHAR := '/.IMMED 0 
) : INTEGER; EXTERN; 


{ Declare a procedure which will display the names of the files 
{ as they are deleted. 

{-> 

PROCEDURE LOG.ROUTINE(FILESPEC : VARYING [A] OF CHAR); 

BEGIN 

WRITELNC'File FILESPEC, ' successfully deleted'); 

END; 


{♦> 

{ Declare a procedure which will notify the user that an error 
< occured. 

<-> 

FUNCTION ERR.ROUTINE(FILESPEC: VARYING [A] OF CHAR; 

RMS.STS, RMS.STV: INTEGER): BOOLEAN; 

BEGIN 

WRITELNCDelete of ', FILESPEC, ' failed ', HEX(RMS.STS)); 
ERR.ROUTINE := TRUE; 

END; 


{+> 

{ Declare a procedure which checks to see if the file should be 
{ deleted. If the filename contains the string 'XYZ', then it is 
{ deleted. 

<-> 

FUNCTION CONFIRM_ROUTINE( FILESPEC: VARYING [A] OF CHAR): BOOLEAN; 
BEGIN 

IF INDEX(FILESPEC, 'XYZ') <> 0 
THEN 

CONFIRM.ROUTINE := TRUE 

ELSE 

CONFIRM.ROUTINE := FALSE; 

END; 

{ The main program begins here. 

<-> 

VAR 

FILES.TO.DELETE, RESULTANT.NAME : VARYING [255] OF CHAR; 
RET.STATUS : INTEGER; 

BEGIN 

WRITE ('Files to delete: '); 

READLN(FILES.TO.DELETE); 

RET.STATUS := LIB$DELETE_FILE( 

FILES.TO.DELETE, ", LOG.ROUTINE, ERR.ROUTINE. 

CONFIRM.ROUTINE..RESULTANT.NAME); 

IF NOT ODD(RET.STATUS) 

THEN 

WRITELNCDelete failed. The error was ', HEX(RET.STATUS)); 

END. 


This PASCAL program prompts the user for file specifications of files to 
be deleted. Of those, it deletes only files which contain the string 'XYZ 7 
somewhere in their resultant file specification. The names of deleted files are 
displayed. 
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LIB$DELETE_LOGICAL—Delete Logical 

Name 



LIB$DELETE_LOGICAL requests the calling process's Command 
Language Interpreter (CLI) to delete a supervisor-mode process 
logical name. LIB$DELETE_LOGICAL provides the same function as 
the DCL command DEASSIGN. 

FORMAT 

LIB$DELETE_LOGICAL log-nam[ r table-descJ 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

log-nam 

VMS Usage: logical-name 
type: character string 

access: read only 

mechanism: by descriptor 

Logical name to be deleted. The log-nam argument is the address of a 
descriptor pointing to this logical name string. The maximum length of a 
logical name is 255 characters. 

table-desc 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the table from which the logical name is to be deleted. The table- 
desc argument is the address of a descriptor pointing to this name string. 

This is an optional argument. If omitted, the LNM$PROCESS table is used. 

DESCRIPTION 

LIB$DELETE_LOGICAL requests the calling process's Command Language 
Interpreter (CLI) to delete a supervisor-mode process logical name. If the 
optional table-desc argument is defined, the logical name is deleted from that 
table. Otherwise, the logical name is deleted from the LNM$PROCESS table. 

Unlike the system service $DELLOG and $DELLNM, LIB$DELETE— 
LOGICAL does not require the caller to be executing in supervisor mode to 
delete a supervisor-mode logical name. 

This procedure is supported for use with the DCL and MCR Command 
Language Interpreters. 

If an image is run directly as a subprocess or as a detached process, there 
is no CLI present to perform this function. In that case, the error status 
LIB$_NOCLI is returned. 
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See the VAX/VMS DCL Dictionary for a description of the DCL command 
DEASSIGN. 


CONDITION 

VALUES 

RETURNED 


SS$_ACCVIO 

SS$_IVLOGNAM 

SS$__I VLOGT AB 
SSS—NOLOGNAM 


SS$_NOPRIV 

SS$_NORMAL 

SSS—TOOMANYLNAM 

LIB$_INVSTRDES 


LIB$_NOCLI 


LIB$_UNECLIERR 


Access violation. The logical name could not be 
read. 

Invalid logical name. The logical name contained 
illegal characters or more than 255 characters. 

Invalid logical name table 

No logical name match. The logical name was not 
defined as a supervisor-mode process logical name. 

No privilege for attempted operation. 

Procedure successfully completed. 

Logical name translation exceeded allowed depth. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the function, 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL Command Language 
Interpreter, please report the problem to DIGITAL 
by means of a Software Performance Report (SPR). 


RTL-89 












Run-Time Library Routines 

LIB$DELETE_SYMBOL 


LIB$DELETE_SYMBOL—Delete CLI 



Symbol 

LIB$DELETE_SYMBOL requests the calling process's Command 
Language Interpreter (CLI) to delete an existing CLI symbol. 

FORMAT 

LIB$DELETE_SYMBOL symbol[,tbl-ind] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

symbol 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the symbol to be deleted by LIB$DELETE_SYMBOL. The symbol 
argument is the address of a descriptor pointing to this symbol string. The 
symbol name is converted to uppercase and trailing blanks are removed 
before use. 

Symbol must begin with a letter, a dollar sign ($), or an underscore (_). 

The maximum length of symbol is 255 characters. 

tbl-ind 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Indicator of the table which contains the symbol to be deleted. The tbl-ind 
argument is the address of a signed longword integer that is this table 
indicator. 

If omitted, the local symbol table is used. The following are possible values 
for the tbl-ind argument. 

Symbolic Name Value Table Used 

LIB$K_CLI_LOCAI_SYM 1 Local symbol table 

LIB$K CLL GLOBAI SYM 2 Global symbol table 
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DESCRIPTION LIB$DELETE_SYMBOL is supported for use with the DCL CLI. The error 

status LIB$_NOCLI will be returned if LIB$DELETE_SYMBOL is used with 
the MCR CLI or called from an image run directly as a subprocess or as a 
detached process. 

LIB$K_CLL_LOCAL_SYM and LIB$K_CLL_GLOBAL_SYM are defined in 
DIGITAL-supplied symbol libraries (macro or module name $LIBCLIDEF) and 
as global symbols. 


CONDITION 

VALUES 

RETURNED 



SSS—NORMAL 

LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_INVSYMNAM 


LIB$_NOCLI 


LIB$_NOSUCHSYM 

LIB$_UNECLIERR 



Procedure successfully completed. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid argument. The value of tbl-ind was invalid. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 

Invalid symbol name. The symbol name contained 
more than 255 characters or did not begin with a 
letter, a dollar sign, or an underscore. 

No CLI present to perform the function. The calling 
process did not have a CLI to perform the function, 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

No such symbol. The symbol was not defined. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL Command Language 
Interpreter, please report the problem to DIGITAL 
by means of a Software Performance Report (SPR). 
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LIB$DELETE_VM_ZONE 


LIB$DELETE_VM_ZONE—Delete Virtual 



Memory Zone 

LIB$DELETE_VM_ZONE deletes a zone and returns all pages owned 
by the zone to the processwide page pool. 

FORMAT 

LIB$DELETE_VM_ZONE zone-id 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

zone-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Zone identifier. The zone-id is the address of a longword that contains the 
identifier of a zone created by a previous call to LIB$CREATE_VM-ZONE or 
LIB$CREATE_USER_VM_ZONE. 

DESCRIPTION 

LIB$DELETE_VM.ZONE deletes a zone and returns all pages owned by the 

zone to the processwide page pool managed by LIB$GET_VM_PAGE. The 
pages are then available for reallocation by later calls to LIB$GET_VM or 

LIB$ GET_VM_P AGE. 

It takes less time to free memory in a single operation by calling 
LIB$DELETE_VM_ZONE than to individually account for and free every 
block of memory that was allocated by calling LIB$GET_VM. 

You must ensure that your program is no longer using any of the memory 
in the zone before you call LIB$DELETE_VM_ZONE. Your program must 
not do any further operations on the zone after you call LIB$DELETE_VM_ 
ZONE. 

If you specified deallocation filling when you created the zone, LIB$DELETE_ 
VM—ZONE will fill all of the allocated blocks that are freed. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

LIB$_BADBLOADR An invalid zone-id argument. 
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LIB$DIGIT_SEP 


LIB$DIGIT. 

_SEP—Get Digit Separator 
Symbol 


LIB$DIGIT_SEP returns the system's digit separator symbol. 

FORMAT 

LI B$ D 1 G 1 T_S E P digit-sep-str [, out-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

digit-sep-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Digit separator symbol returned by LIB$DIGIT_SEP. The digit-sep-str 
argument is the address of a descriptor pointing to the digit separator. 


out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of characters written into digit-sep-str, not counting padding in 
the case of a fixed-length string. The out-len argument is the address of an 
unsigned word containing the length of the digit separator symbol. If the 
input string is truncated to the size specified in the digit-sep-str descriptor, 
out-len is set to this size. Therefore, out-len can always be used by the 
calling program to access a valid substring of digit-sep-str. 


DESCRIPTION LIB$DIGIT_SEP returns the symbol that is used to separate groups of three 

digits in the integer part of a number, for readability. A common digit 
separator is a comma (,) as in 3,006,854. 


LIB$DIGIT_SEP attempts to translate the logical name SYS$DIGIT_SEP as a 
process, group, or system logical name. If the translation fails, LIB$DIGIT_ 
SEP returns a comma (,), the United States digit separator. If the translation 
succeeds, the text produced is returned. Thus, a system manager can define 
SYS$DIGIT_SEP as a system-wide logical name to provide a default for all 
users, and an individual user with a special need can define SYS$DIGIT_SEP 
as a process logical name to override the default symbol. For example, you 
may wish to use the French digit seperator, the period (.). 

BASIC implicitly uses LIB$DIGIT_SEP. 


RTL-93 













Run-Time Library Routines 

LIB$DIGIT_SEP 


CONDITION SS$_NORMAL 
VALUES LIB$_STRTRU 

RETURNED 

LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Successfully completed, but the digit separator 
string was truncated. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 


EXAMPLE 

PROGRAM DIGIT_SEP(INPUT. OUTPUT); 

<♦> 

{ This program uses LIB$DIGIT_SEP to return current 
{ value of SYS$DIGIT_SEP. 

{-> 

PROCEDURE LIB$DIGIT_SEP(%DESCR DIGIT.SEPSTR : VARYING [A] 
OF CHAR; */,REF OUT.LEN : INTEGER); EXTERN; 

VAR 

SEPARATOR : VARYING [256] OF CHAR; 

LENGTH : INTEGER; 

BEGIN 

LIB$DIGIT_SEP(SEPARATOR. LENGTH); 

WRITELN(•104'.SEPARATOR.'567'.SEPARATOR.•934'); 

END. 


This PASCAL example demonstrates how to use LIB$DIGIT_SEP. The output 
generated by this program is as follows: 

104,567,934 


RTL-94 










Run-Time Library Routines 

LIB$DISABLE_CTRL 


LIB$DISABLE_CTRL—Disable CLI 

Interception of 
Control Characters 


LIB$DISABLE_CTRL requests the calling process's Command 
Language Interpreter (CLI) to not intercept the selected control 
characters when they are typed during an interactive terminal 
session. LIB$DISABLE_CTRL provides the same function as the 

DCL command SET NOCONTROL. 

FORMAT 

LIB$DISABLE_CTRL disable-msk[,old-msk] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS disable-msk 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Bit mask indicating which control characters are not to be intercepted. The 
disable-msk argument is the address of an unsigned longword containing 
this bit mask. 

Each of the 32 bits corresponds to one of the 32 possible control characters. If 
a bit is set, the corresponding control character is no longer intercepted by the 
CLI. Currently, only bits 20 and 25, corresponding to CTRL/T and CTRL/Y, 
are recognized. 

The following mask is defined in DIGITAL-supplied symbol libraries to 
specify the value of disable-msk. 


Symbol 

Hex Value 

Function 

LIB$M_CLI_CTRLT 

%X / 00100000' 

Disables CTRL/T 

LI B$M CU CTRLY 

%X'02000000 / 

Disables CTRL/Y 


If a set bit does not correspond to a character which the CLI can intercept, 
LIB$DISABLE_CTRL returns an error. 
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LIB$DISABLE_CTRL 


old-msk 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Previous bit mask. The old-msk argument is the address of an unsigned 
longword into which LIB$DISABLE_CTRL writes the old bit mask. The old 
bit mask is of the same form as disable-msk. 


DESCRIPTION The DCL and MCR CLIs can intercept the CTRL/Y control character. The 

DCL CLI can intercept the CTRL/T character. See the VAX/VMS DCL 
Dictionary for information on how the DCL CLI processes control characters, 
and see the VAX-11 /RSX-11M User's Guide for information on how the MCR 
CLI processes control characters. 

LIB$DISABLE_CTRL is supported for use with the DCL and MCR CLIs. If an 
image is run directly as a subprocess or as a detached process, there is no CLI 
present to perform this function. In those cases, LIB$DISABLE_CTRL returns 
the error status LIB$_NOCLI. 



CONDITION SS$_NORMAL 
VALUES LIB$_INVARG 

RETURNED 

LIB$_NOCLI 


LIB$_UNECLIERR 


Procedure successfully completed. 

Invalid argument. A bit in disable-msk was set 
which did not correspond to a control character 
supported by the CLI. 

No CLI present. Either the calling process did not 
have a CLI to perform the function, or the CLI did 
not support the request type. Note that an image 
run as a subprocess or detached process does not 
have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL or MCR CLIs, please 
report the problem to DIGITAL by means of a 
Software Performance Report (SPR). 
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LIB$DO_COMMAND 


LIB$DO_COMMAND—Execute Command 



LIB$DO_COMMAND stops program execution and directs the 
Command Language Interpreter to execute a command which 
you supply as the argument. If successful, LIB$DO_COMMAND 
does not return control to the calling program. Instead, LIB$DO_ 
COMMAND begins execution of the specified command. 

If you want control to return to the caller, use LIB$SPAWN instead. 

FORMAT 

LIB$DO_COMMAND cmd-text 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

cmd-text 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Text of the command which LIB$DO_COMMAND executes. The cmd-text 
argument is the address of a descriptor pointing to the command text. If 
cmd-text contains embedded blanks, it must be enclosed by quotation marks. 
The maximum length of the command is 255 characters. 

DESCRIPTION 

LIB$DO_COMMAND terminates your current image and then executes the 
contents of cmd-text as a command. The command is parsed using normal 
DCL rules. 

LIB$DO__COMMAND is especially useful when you wish to execute a CLI 
command after your program has finished executing. For example, you could 
use the procedure to execute a SUBMIT or PRINT command to handle a file 
that your program has created. 

Because of the following restrictions on LIB$DO_COMMAND, you should be 
careful when you incorporate it in your program. 

• During the call to LIB$DO_COMMAND, the current image exits and 
control cannot return to it. 

• The text of the command is passed to the current Command Language 
Interpreter. Because you can define your own CLI in addition to DCL 
and MCR, you must make sure that the command will be handled by the 
intended CLI. 

• If LIB$DO_COMMAND is called from an image run directly as a 
subprocess or detached process, it will not execute correctly, since no CLI 
is associated with a subprocess. 


RTL-97 













Run-Time Library Routines 

LI B$DO_COMMAND 


LIB$DO_COMMAND is supported for use with the DCL and MCR CLIs. 

If an image is run directly as a subprocess or as a detached process, there 
is no CLI present to perform this function. In those cases, the error status 
LIB$_NOCLI is returned. Note that the command can execute an indirect file 
using the at-sign (@) feature of DCL. 


CONDITION LIB$_INVARG 

VALUES 

RETURNED lib$_nocli 


LIB$_UNECLIERR 


Invalid argument. Cmd-txt was more than 255 
characters. 

No CLI present. The calling process did not have 
a CLI to perform the function, or the CLI did not 
support the request type. Note that an image run 
as a subprocess or detached process does not 
have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL or MCR CLIs, please 
report the problem to DIGITAL by means of a 
Software Performance Report (SPR). 


EXAMPLE 


PROGRAM D0_C0MMAND(INPUT, OUTPUT); 

{♦> 

{ This example uses LIB$DO_COMMAND to execute 
{ any DCL command that is entered by the user 
{ at the prompt. 

{-> 

PROCEDURE LIB$DO_COMMAND(CMDTXT : VARYING [A] OF CHAR); 

EXTERN; 

VAR 

COMMAND : VARYING [256] OF CHAR; 

BEGIN 

WRITELNCENTER THE COMMAND YOU WANT TO EXECUTE: '); 
READLN(COMMAND); 

LIB$D0_C0MMAND(COMMAND); 

END. 


This PASCAL program shows how to call LIB$DO_COMMAND. One 
example of the output of this program is as follows: 

$ RUN DO.COMMAND 

ENTER THE COMMAND YOU WANT TO EXECUTE: SHOW TIME 
30-MAY-1985 14:07:28 
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LIB$EDIV 


LIB$EDIV- 

—Extended-Precision Divide 

LIB$EDIV performs extended-precision division. LIB$EDIV makes 
the VAX EDIV instruction available as a callable procedure. 

FORMAT 

LI B$EDIV divisor, dividend,quotient remainder 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

divisor 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Divisor. The divisor argument is the address of a signed longword integer 
containing the divisor. 

dividend 

VMS Usage: quadword_signed 
type: quadword integer (signed) 

access: read only 

mechanism: by reference 

Dividend. The dividend argument is the address of a signed quadword 
integer containing the dividend. 

quotient 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Quotient. The quotient argument is the address of a signed longword integer 
containing the quotient. 

remainder 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Remainder. The remainder argument is the address of a signed longword 
integer containing the remainder. 
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LIB$EDIV 


CONDITION SS$_NORMAL 
VALUES SS$_INTOVF 

RETURNED 

SS$_INTDIV 


Normal successful operation. 

Integer overflow. The quotient is replaced by bits 
31:0 of the dividend, and the remainder is replaced 
by zero. 

Integer divide by zero. The quotient is replaced 
by bits 31:0 of the dividend, and the remainder is 
replaced by zero. 


EXAMPLE 


C+ 

C This FORTRAN program demonstrates how to use LIB$EDIV. 

c- 

INTEGER DIVISOR,DIVIDEND(2).QUOTIENT,REMAINDER 
C+ 

C Find the quotient and remainder of 4600387192 divided by 4096. 

C Since 4600387192 is too large to store as a longword, use LIB$EDIV. 

C- 

DIVISOR = 4096 
C+ 

C The dividend must be represented as a quadword. To do this use a vector 
C o 1 length 2. The first element is the low order longword, and the second 
C element is the high order longword. 

C Now. 4600387192 = '00000000112345678'x. So, 

C- 

DIVIDEND(l) = '12345678'X 
DIVIDEND(2) * '00000001'X 

C+ 

C Compute the quotient and remainder of 4600387192 divided by 4096. 

C- 

RETURN * LIBIEDIV(DIVISOR,DIVIDEND,QUOTIENT.REMAINDER) 

TYPE *,'The longword integer quotient of 4600387192/4096 is:' 
TYPE*,' '.QUOTIENT 

TYPE *,'The longword integer remainder of 4600387192/4096 is:' 

TYPE *.' '. REMAINDER 

END 


This FORTRAN example demonstrates how to call LIB$EDIV. The output 
generated by this program is as follows: 

The longword integer quotient of 4600387192/4096 is: 

1123141 

The longword integer remainder of 4600387192/4096 is: 

1656 
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LIB$EMODx 


LIB$EMODx—Extended Multiply and 



Integerize Procedures 

The LIB$EMODx procedures perform accurate range reduction of 
floating-point arguments. They provide the higher-level language 
users with the capability to use the VAX hardware instructions 
EMODF, EMODD, EMODG, and EMODH. 

FORMAT 

LIB$EMODF multiplier mult-ext multiplicand ,int 
,fract 

LIBSEMODD multiplier,mult-ext,multiplicand,int 
,fract 

LI B$EMODG multiplier,mult-ext multiplicand ,int 
,fract 

LIB$EMODH multiplier mult-ext multiplicand ,int 
,fract 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

multiplier 

VMS Usage: floating-point 

type: D__floating, F_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Multiplier. For LIB$EMODF, the multiplier argument is an F_floating 
number. For LIB$EMODD, the multiplier argument is a D_floating number. 
For LIB$EMODG, the multiplier argument is a G_floating number. For 
LIB$EMODH, the multiplier argument is an H_floating number. 

mult-ext 

VMS Usage: byte_signed, word_unsigned 
type: byte integer (signed), word (unsigned) 

access: read only 

mechanism: by reference 

The left-justified multiplier-extension bits. For F_floating and D_fioating, the 
mult-ext argument is an unsigned byte. For G_floating and H_floating, the 
mult-ext argument is an unsigned word. 
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LI B$EMODx 


multiplicand 

VMS Usage: floating-point 

type: D—floating, F_floating, G_floating, H_floating 

access: read only 

mechanism: by reference 

Multiplicand. For LIB$EMODF, the multiplicand argument is an F_floating 
number. For LIB$EMODD, the multiplicand argument is a D—floating 
number. For LIB$EMODG, the multiplicand argument is a G_floating 
number. For LIB$EMODH, the multiplicand argument is an H_floating 
number. 


int 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Integer portion of the result. The int argument is the address of a signed 
longword integer containing the integer portion of the result. 


tract 

VMS Usage: floating-point 

type: D—floating, F_floating, G_floating, H_floating 

access: write only 

mechanism: by reference 

Fractional portion of the result. For LIB$EMODF, the fract argument is an 
F—floating number. For LIB$EMODD, the fract argument is a D—floating 
number. For LIB$EMODG, the fract argument is a G— floating number. For 
LIB$EMODH, the fract argument is an H_floating number. 


DESCRIPTION The floating-point multiplier extension operand (second operand) is 

concatenated with the floating-point multiplier (first operand) to gain x 
additional low-order fraction bits. The multiplicand is multiplied by the 
extended multiplier. After multiplication, the integer portion is extracted and 
a y-bit floating-point number is formed from the fractional part of the product 
by truncating extra bits. 

The multiplication yields a result equivalent to the exact product truncated 
to a fraction field of y bits. With respect to the result as the sum of an 
integer and fraction of the same sign, the integer operand is replaced by the 
integer part of the result and the fraction operand is replaced by the rounded 
fractional part of the result. 

The values of x and y are listed below. 


Procedure 

X 

Bits 

y 

LIBSEMODF 

8 

7:0 

32 

LIB$EMODD 

8 

7:0 

64 

LIBSEMODG 

11 

15:5 

64 

LIB$EMODH 

15 

15:1 

128 
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LIB$EMODx 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SSS—INTOVF 

SS$_FLTUND 

SS$_ROPRAND 


Routine successfully completed. 

Integer overflow. The integer operand is replaced 
by the low-order bits of the true result. Floating 
overflow is indicated by SS$_INTOVF also. 

Floating underflow. The integer and fraction 
operands are replaced by zero. 

Reserved operand. The integer and fraction 
operands are unaffected. 
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LIB$EMUL 


LIB$EMUL—Extended-Precision Multiply 



LIB$EMUL performs extended-precision multiplication. LIB$EMUL 
makes the VAX EMUL instruction available as a callable procedure. 

FORMAT 

LIB$EMUL multiplier multiplicand ,addend,product 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

multiplier 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Multiplier used by LIB$EMUL in the extended-precision multiplication. The 
multiplier argument is the address of a signed longword integer containing 
the multiplier. 

multiplicand 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Multiplicand used by LIB$EMUL in the extended-precision multiplication. 

The multiplicand argument is the address of a signed longword integer 
containing the multiplicand. 

addend 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Addend used by LIB$EMUL in the extended-precision multiplication. The 
addend argument is the address of a signed longword integer containing the 
addend. 

product 

VMS Usage: quadword_signed 
type: quadword integer (signed) 

access: write only 

mechanism: by reference 

Product of the extended-precision multiplication. The product argument is 
the address of a signed quadword integer into which LIB$EMUL writes the 
product. 
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LIB$EMUL 


DESCRIPTION 

The multiplicand argument is multiplied by the multiplier argument giving a 
double-length result. The addend argument is sign-extended to double-length 
and added to the result. LIB$EMUL then writes the result into the product 
argument. 

For more information, see the VAX-11 Architecture Reference Manual. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 
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LIB$ENABLE_CTRL 


LIB$ENABLE_CTRL—Enable CLI 

Interception of 

Control Characters 


LIB$ENABLE_CTRL requests the calling process's Command 
Language Interpreter (CLI) to resume interception of the selected 
control characters when they are typed during an interactive terminal 
session. LIB$ENABLE_CTRL provides the same function as the DCL 
command SET CONTROL. 

FORMAT 

LIB$ENABLE_CTRL enable-msk [,old-msk] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

enable-msk 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Bit mask indicating for which control characters LIB$ENABLE_CTRL is to 
enable interception. The enable-msk argument is the address of an unsigned 
longword containing this bit mask. Each of the 32 bits corresponds to 
one of the 32 possible control characters. If a bit is set, the corresponding 
control character is intercepted by the CLI. Currently, only bits 20 and 25, 
corresponding to CTRL/T and CTRL/Y, are recognized. 

The following mask is defined in DIGITAL-supplied symbol libraries to 
specify the value of enable-msk. 


Symbol 

Hex Value 

Function 

LIB$M_CLI_CTRLT 

roX'ooiooooo 7 

Enables CTRL/T 

LIB$M_CLI_CTRLY 

%X / 02000000 / 

Enables CTRL/Y 


If a set bit does not correspond to a character which the CLI can intercept, an 
error is returned. 


old-msk 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Previous bit mask. The old-msk argument is the address of an unsigned 
longword containing the old bit mask. The old bit mask is of the same form 

as enable-msk. 
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LIB$ENABLE_CTRL 


DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


LIB$ENABLE_CTRL provides the functions of the DCL SET CONTROL 
command. Normally, CTRL/Y interrupts the current command, command 
procedure, or image. After a call to LIB$DISABLE_CTRL, CTRL/Y is treated 
like CTRL/U followed by a carriage return. LIB$ENABLE_CTRL restores the 
normal operation of CTRL/Y or CTRL/T. 

Both the DCL and MCR CLIs can intercept control characters. See the 
VAX/VMS DCL Dictionary for information on how the CLI processes control 
characters, and see the VAX-11 /RSX-11M User's Guide for information on 
how the MCR CLI processes control characters. 

LIB$ENABLE_CTRL is supported for use with the DCL or MCR CLIs. 

If an image is run directly as a subprocess or as a detached process, there 
is no CLI present to perform this function. In those cases, the error status 
LIB$_NOCLI is returned. 


SS$_NORMAL 

LIB$_JNVARG 

LIB$_NOCLI 


LIB$_UNECLIERR 


Procedure successfully completed. 

Invalid argument. A bit in enable-msk was set 
which did not correspond to a control character 
supported by the CLI. 

No CLI present. The calling process did not have 
a CLI to perform the function, or the CLI did not 
support the request type. Note that an image run 
as a subprocess or detached process does not 
have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL or MCR CLIs, please 
report the problem to DIGITAL by means of a 
Software Performance Report (SPR). 
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LIB$ESTABLISH 


LIB$ESTABLISH—Establish a Condition 

Handler 


LIB$ESTABLISH moves the address of a condition handling routine 
(which can be a user-written or a library procedure) to longword 0 
of the stack frame of the caller of LIBSESTABLISH. 

FORMAT 

LIBSESTABLISH new-handier 

RETURNS 

VMS Usage: procedure 
type: procedure entry mask 

access: write only 

mechanism: by reference 

Previous contents of SF$A_HANDLER (longword 0) of the caller's stack 
frame; zero if no handler existed. 

ARGUMENT 

new-handier 

VMS Usage: procedure 
type: procedure entry mask 

access: read only 

mechanism: by reference 

Routine to be set up as the condition handler. The new-handier argument is 
the address of the procedure entry mask to this routine. 

DESCRIPTION 

LIBSESTABLISH moves the address of a condition-handling routine to 
longword 0 of the stack frame of the caller of LIBSESTABLISH. This 
condition-handling routine then becomes the caller's condition handler. 
LIBSESTABLISH returns the previous contents of longword 0. This can either 
be the address of the caller's previous condition handler or zero if no handler 
existed. 


The new condition handler remains in effect for your procedure until you call 
LIB$REVERT or until control returns to the caller of the procedure that called 
LIB$ESTABLISH. Once this happens, you must call LIB$ESTABLISH again if 
the same (or a new) condition handler is to be associated with the procedure 
that called LIB$ESTABLISH. 

LIB$ESTABLISH modifies the caller's stack frame. 

LIB$ESTABLISH is provided primarily for use with languages without built-in 
error handling facilities. Do not use LIBSESTABLISH with languages that 
provide error handling, such as BASIC, COBOL, PASCAL, and PL/I. Use 
of this procedure with these languages may adversely affect the behavior of 
your program. The language-support library for these languages depends on 
predefined language-specific handlers. Also, the handler address is used to 
identify the stack frames of procedures written in these languages. See the 
documentation for the language you are using for more information about 
how that language handles errors. 
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In MACRO, you merely use the following instruction instead of calling 
LIB$ESTABLISH: 

MOVAB HANDLER, (FP) ; set handler address 

; in current stack frame 


CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 


C+ 

C This FORTRAN program demonstrates the 
C use of LIBIESTABLISH. 

C 

C This is the main program. 

C- 

EXTERNAL LOG.HANDL 
CHARACTER TIMBUF 

OPEN (UNIT=99, FILE = ’ERRLOG', STATUS = 'NEW') 

CALL LIB$ESTABLISH (LOG.HANDL) 

CALL SYS$BINTIM (TIMBUF, TIMADR) 

C+ 

C The rest of the main program would go here. 

C- 

END 

INTEGER*4 FUNCTION LOG.HANDL (SIGARGS, MECHARGS) 
INTEGER*4 SIGARGS (*) , MECHARGS (5) 

C+ 

C This is the handler to journal any signaled error messages. 
C- 

INCLUDE '($SSDEF)' 

EXTERNAL PUT.LINE 

LOG.HANDL = SS$_RESIGNAL 

CALL SYSSPUTMSG (SIGARGS. PUT.LINE, ) 

RETURN 

END 

C+ 

C This is the action subroutine. 

C- 

LOGICAL+4 FUNCTION PUT.LINE (LINE) 

CHARACTER*(*)LINE 
PUT.LINE = .FALSE. 

100 WRITE (99,200)LINE 

200 FORMAT (A) 

RETURN 

END 


In this FORTRAN example, the function log_handl is the condition handler 
for the program, and thus receives control when an error occurs. 
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LIB$EXTV—Extract a Field and 
Sign-Extend 

LIB$EXTV returns a sign-extended longword field that has been 
extracted from the specified variable bit field. LIB$EXTV makes the 
VAX EXTV instruction available as a callable procedure. 


FORMAT LIB$ EXTV pos , size,base 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword integer (signed) 
write only 
by value 


Field extracted by LIB$EXTV, sign-extended to a longword. 


ARGUMENTS 


pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Position (relative to the base address) of the first bit in the field that 
LIB$EXTV extracts. The pos argument is the address of a signed longword 
integer containing the position. 


size 

VMS Usage: byte.unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Size of the bit field LIB$EXTV extracts. The size argument is the address of 
an unsigned byte containing the size. The maximum size is 32 bits. 


base 


VMS Usage: 
type: 
access: 
mechanism: 


longword—unsigned 
longword (unsigned) 
read only 
by value 


Base address of the bit field LIB$EXTV extracts from the specified variable 
bit field. The base argument is an unsigned longword containing the base 
address. 
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DESCRIPTION The variable-length bit field is a VAX data type used to store small integers 

packed together in a larger data structure. It is often used to store single flag 
bits. 

Three scalar attributes define a variable bit field. 

• The base address is the address of a byte in memory that serves as a 
reference point for locating the bit field. 

• The bit position is a signed longword containing the displacement of the 
least significant bit of the field with respect to the bit zero of the base 
address. 

• The size is a byte integer indicating the size of the bit field in bits (in 
the range 0 <= size <§= 32). That is, a bit field can be no more than one 
longword in length. 

A variable-length bit field has the following format. The shaded area 
indicates the field. 


P*S-1 P 0 



LIB$EXTV 


S = Size of field in bits- 

P = Bit displacement of field - 
from bit zero of address A 


ZK-1940-84 


Bit fields are zero-origin, which means that the procedure regards the first bit 
in the field as being the zero position. For more detailed information on VAX 
bit number and data formats, see the VAX-11 Architecture Reference Manual. 

The Run-Time Library procedures for performing operations on variable- 
length bit fields give higher-level languages direct access to the bit field 
instructions in the VAX instruction set. 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 


A reserved operand fault occurs if a size greater 
than 32 is specified. 
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EXAMPLE 


SIGN.EXTEND: PROCEDURE OPTIONS (MAIN); 

DECLARE LIBIEXTV ENTRY 

(FIXED BINARY (31), /* Address of longword containing 

/* beginning bit position */ 

FIXED BINARY (7), /* Address of byte containing size 

/* of field */ 

FIXED BINARY (31)) /* Address of field */ 

RETURNS (FIXED BINARY (31)); /* Return value */ 

DECLARE (VALUE, SMALL.INT) FIXED BINARY (31); 

ON ENDFILE (SYSIN) STOP; 


DO WHILE (* 1'B); /* Loop continuously, until end of file */ 

PUT SKIP(2); 

GET LIST (VALUE) OPTIONS (PROMPT ('Value: ')); 

SMALL.INT = LIB$EXTV ( 0, 4, VALUE); /* Extract and sign-extend 

/* first 4 bits */ 

PUT SKIP LIST (VALUE, SMALL.INT); 

END; 

END SIGN.EXTEND; 


This PL/I program extracts a field and returns it sign-extended into a 
longword. 
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LIB$EXTZV—Extract a Zero-Extended 

Field 


LIB$EXTZV returns a longword zero-extended field that has been 
extracted from the specified variable bit field. LIB$EXTZV makes 
the VAX EXTZV instruction available as a callable procedure. 

FORMAT 

LI B$ EXTZV pos, size , base 

RETURNS 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by value 

Field extracted by LIB$EXTZV, zero-extended to a longword. 


ARGUMENTS 


pos 

VMS Usage: longword_signed 
type: longword (signed) 

access: read only 

mechanism: by reference 

Position (relative to the base address) of the first bit in the field LIB$EXTZV 
extracts. The pos argument is the address of a signed longword integer 
containing the position. 


size 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Size of the bit field LIB$EXTZV extracts. The size argument is the address of 
an unsigned byte containing the size. The maximum size is 32 bits. 


base 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by value 

Base address of the bit field LIB$EXTZV extracts. The base argument is the 
address of an unsigned longword containing the base address. 
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DESCRIPTION The variable-length bit field is a VAX data type used to store small integers 

packed together in a larger data structure. It is often used to store single flag 
bits. 

Three scalar attributes define a variable bit field. 

• The base address is the address of the byte in memory that serves as a 
reference point for locating the bit field. 

• The bit position is a signed longword containing the displacement of the 
least significant bit of the field with respect to the bit zero of the base 
address. 

• The size is a byte integer indicating the size of the bit field in bits (in 
the range 0 <e= size 32). That is, a bit field can be no more than one 
longword in length. 

A variable-length bit field has the following format. The shaded area 
indicates the field. 


P + S-1 P 0 



S = Size of field in bits 


:A LIB$EXTZV 


P = Bit displacement of field - 
from bit zero of address A 


ZK-1941-84 


Bit fields are zero-origin, which means that the procedure regards the first 
bit in the field as being the zero position. For more detailed information on 
VAX bit numbering and data formats, see the VAX-11 Architecture Reference 
Manual. 

The Run-Time Library procedures for performing operations on variable- 
length bit fields give higher-level languages direct access to the bit field 
instructions in the VAX instruction set. 


CONDITION SS$_ROPRAND 

VALUE 

SIGNALED 


A reserved operand fault occurs if a size greater 
than 32 is specified. 
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LIB$FFx—Find First Clear or Set Bit 

LIB$FFC and LIB$FFS search the field specified by the start position, 
size, and base for the first clear or set bit. LIB$FFC and LIB$FFS 
make the VAX FFC and FFS instructions available as callable 
procedures. 


FORMAT 

LIB$FFC 

LIBSFFS 

start-pos ,size ,base, find-pos 
start-pos ,size ,base, find-pos 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS start-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Starting position, relative to the base address, of the bit field to be searched 
by LIB$FFx. The start-pos argument is the address of a signed longword 
integer containing the starting position. 


size 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Number of bits to be searched by LIB$FFx. The size argument is the address 
of an unsigned byte containing the size of the bit field to be searched. The 
maximum size is 32 bits. 


base 


VMS Usage: 
type: 
access: 
mechanism: 


longword_unsigned 
longword (unsigned) 
read only 
by reference 


Base address of the bit field which LIB$FFx searches. The base argument is 
the address of an unsigned longword containing the base address. 


find-pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Bit position of the first bit in the specified state (clear or set), relative to the 
base address. The find-pos argument is the address of a signed longword 
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integer into which LIB$FFC writes the position of the first clear bit and into 
which LIB$FFS writes the position of the first set bit. 

DESCRIPTION 

LIB$FFC searches the field specified by the start position, size, and base for 
the first clear bit. LIB$FFS searches the field for the first set bit. 

If a bit in the specified state is found, LIB$FFx writes the position (relative to 
the base) of that bit into find-pos and returns a success status. If no bits are 
in the specified state or if size is zero, LIB$FFx returns LIB$_NOTFOU and 
sets find-pos to the starting position plus the size. 

LIB$FFx regards the first bit in the field as being the zero position. For more 
detailed information on VAX bit numbering and data formats, see the VAX-11 
Architecture Reference Manual. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Routine successfully completed. A bit in the 

specified state was found. 

LIB$_NOTFOU A bit in the specified state was not found. 

CONDITION 

VALUE 

SIGNALED 

SS$_ROPRAND Reserved operand fault. A size greater than 32 was 

specified. 
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LIB$FILE_SCAN—File Scan 

LIB$FILE_SCAN searches an area, such as a directory, for all files 
matching the file specification given and transfers program execution 
to the specified user-written routine. Wildcards are acceptable. An 
action routine is called for each file and/or error found. LIB$FILE_ 
SCAN allows the search sequence to continue even if an error 
occurs while processing a particular file. 


FORMAT LIB$FILE_SCAN fab ,success-rtn ,error-rtn 

[, context] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


fab 

VMS Usage: 
type: 
access: 
mechanism: 


fab 

unspecified 
read only 
by reference 

File Access Block (FAB) referencing a valid NAM block. The fab argument 
is the address of the FAB which contains the address and length of the file 
specification being searched for by LIB$FILE_SCAN. 


success-rtn 


VMS Usage: 
type: 
access: 
mechanism: 


procedure 

procedure entry mask 
function call (before return) 
by reference, procedure reference 


User-supplied success routine that LIB$FILE_SCAN calls when a file is 
found. The success-rtn argument is the address of the procedure entry mask 
to the success routine. The success routine is invoked with the FAB address 
that was passed to LIB$FILE_SCAN. The user context may be pased to this 
routine using the FAB$L_CTX field in the FAB. 


error-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied error routine that LIB$FILE_SCAN calls when it encounters an 
error. The error-rtn argument is the address of the procedure entry mask to 
the error routine. The error routine is called with the FAB argument that was 
passed to LIB$FILE_SCAN. 
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context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Default file context used in processing file specifications for multiple input 
files. The context argument is the address of a longword, which must be 
initialized to zero by your program before the first call to LIB$FILE_SCAN. 
After the first call, LIB$FILE_SCAN maintains this longword. You must not 
change the value of context in subsequent calls to LIB$FILE SCAN. 

Name blocks and file specification strings are allocated by LIB$FILE_SCAN, 
and context is used to retain their addresses so they may be deallocated 
later. If the context argument is not passed, unspecified portions of the file 
specification will be inherited from the previous file specification processed, 
rather than from multiple input file specifications. 

DESCRIPTION 

LIB$FILE_SCAN is called with the address of a File Access Block (FAB) and 
calls an action routine for each file found and/or error returned. LIB$FILE_ 
SCAN allows the search sequence to continue even if an error occurs while 
processing a particular file. 

If this routine is called once for each file specification argument in a command 
line, portions of the file specifications which are not specified by the user are 
inherited from the last files processed. 

You must call LIB$FILE_SCAN_END before initiating a new sequence of 
calls to LIB$FILE_SCAN. 

CONDITION 

VALUES 

RETURNED 

Any condition value returned by the Record Management Service (RMS), 
Parse 
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LIB$FILE_SCAN_END—End of File Scan 



LIB$FILE_SCAN_END is called after each sequence of calls to 
LIB$FILE_SCAN. LIB$FILE_SCAN_END deallocates any saved 
Record Management Service (RMS) context and deallocates the 
virtual memory which had been allocated for holding the related file 
specification information. 

FORMAT 

LIB$FILE_SCAN_END fab ^context] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

fab 

VMS Usage: fab 
type: unspecified 

access: modify 

mechanism: by reference 

File Access Block (FAB) used with LIB$FILE_SCAN. The fab argument is 
the address of the FAB which contains the address and length of the file 
specification. 

context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Temporary default context used in LIB$FILE_SCAN. The context argument is 
the address of a longword containing this temporary default context. 

DESCRIPTION 

LIB$FILE_SCAN_END should be called by your program after each sequence 
of calls to LIB$FILE_SCAN. It performs a parse of the null string to deallocate 
any saved RMS context and to deallocate any virtual memory which had 
been allocated for holding the related file specification information. 

If LIB$FILE_SCAN is directed to process the specifications for multiple 
input files, LIB$FILE_SCAN_END is used to deallocate those saved file 
specifications. If LIB$FILE_SCAN__END is called by your program after each 
sequence of calls to LIB$FILE_SCAN, it will prevent the defaults from the 
previous call from affecting context value in the next call to LIB$FILE_SCAN. 
LIB$FILE_SCAN_END does this by replacing the context value passed to it 
with a temporary context value that your program passes to LIB$FILE_SCAN 
the next time it is called. 
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CONDITION RMSS—NORMAL 
VALUES RMS$_FAB 

RETURNED 


Procedure successfully completed. 


The fab argument is not the address of a valid 
FAB. 
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LIB$FIND. 

-FILE—Find File 

LIB$FIND_FILE is called with a wildcard file specification for which 
it searches. LIB$FIND_FILE returns all file specifications that satisfy 
that wildcard file specification. 

FORMAT 

LI B$FI N D_F 1LE file-spec,result-spec, context 
[, default-spec] [, related-spec] 

[, stv-addr] [, user-flags] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

file-spec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification, which may contain wildcards, that LIB$FIND_FILE uses 
to search for the desired file. The file-spec argument is the address of a 
descriptor pointing to the file specification. The maximum length of a file 
specification is 255 bytes. 

The file specification used may also contain a search list logical name. If 
present, the search list logical name elements can be used as accumulative to 
related file specifications, so that portions of file specifications not specified by 
the user will be inherited from previous file specifications. 

result-spec 

VMS Usage: char_string 
type: character string 

access: modify 

mechanism: by descriptor 

Resultant file specification that LIB$FIND_FILE returns when it finds a 
file that matches the specification in the file-spec argument. The result- 
spec argument is the address of a descriptor pointing to the resultant file 
specification. 

context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Zero or an address of an internal FAB/NAM buffer from a previous call to 
LIB$FIND_FILE. The context argument is an unsigned longword integer 
containing the address of the context. LIB$FIND_FILE uses this argument 
to retain the context when processing multiple input files. Portions of file 
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specifications that the user does not specify are inherited from the last files 
processed because the file contexts are retained in this argument. 

default-spec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Default file specification. The default-spec argument is the address of a 
descriptor pointing to the default file specification. 

related-spec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Related file specification containing the context of the last file processed. The 
related-spec argument is the address of a descriptor pointing to the related 
file specification. 


stv-addr 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Record Management Service (RMS) secondary status value from a failing 
RMS operation. The stv-addr argument is an unsigned longword containing 
the address of a longword-length buffer to receive the RMS secondary status 
value (usually returned in the file access block field, FAB$L_STV). 


user-flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

User flags. The user-flags argument is the address of an unsigned longword 
containing the user flags. 

The flag bits and their corresponding symbols are described in the following 
table. 
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BIT SYMBOL DESCRIPTION 

0 NOWILD If set, LIB$FIND_FILE returns an error if a wildcard character 

is input. 

1 MULTIPLE If set, this performs temporary defaulting for multiple 

input files and the related-spec argument is ignored. 

See description of context in LIB$FILE_SCAN. Each time 
LIB$FIND_FILE is called with a different file specification, 
the specification from the previous call is automatically 
used as a related file specification. This allows parsing 
of the elements of a search-list logical name such as 
DISK2:[SMITH] FIL1 .TYP,FIL* *2.TYP, and so on. Use of 
this feature is required to get the desired defaulting with 
search list logical name. LIB$FIND_FILE_END must be called 
between each command line in interactive use or the defaults 
from the previous command line will affect the current file 
specification. 


DESCRIPTION LIB$FIND_FILE searches for a certain wildcard file specification and returns 
all file specifications that satisfy that wildcard file specification. 

If you make multiple calls to LIB$FIND_FILE, be aware of the following 
behavior: 

• If, when making the multiple calls, the NO WILD bit is not set and the file 
specification does not contain any wildcard characters, LIB$FIND_FILE 
returns the appropriate file name on the first call and the condition value 
RMS$_NMF on the next call. 

• If you make the multiple calls with the NO WILD bit set and the same 
nonwildcard file specification, LIB$FIND_JFILE returns the file name on 
the first call as well as each subsequent call. 


CONDITION RMS$_NORMAL 
VALUES LIBS—NOWILD 

RETURNED 


RMS$_NMF 


Routine completed successfully. 

A wildcard character was present in the file 
specification parsed and the wildcard flag bit was 
set to no wildcard. (This is actually the SHR$_ 
NOWILD error message after application of the 
LIB$ facility code.) 

No more files. 


Any condition value returned by RMS Parse and Search services, LIB$GET_ 
VM, LIB$FREE_VM, or LIB$SCOPY_R_DX. 
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LIB$FIND_ 

-FILE—END—End of Find File 

LIB$FIND_FILE_END is called once after each sequence of calls to 
LIB$FIND_FILE. LIB$FIND_FILE_END deallocates any saved Record 
Management Service (RMS) context and deallocates the virtual 
memory used to hold the allocated context block. 

FORMAT 

LIB$FIND_FILE_END context 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

context 

VMS Usage: context 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Zero or the address of a FAB/NAM buffer from a previous call to LIB$FIND_ 
FILE. The context argument is the address of a longword that contains this 
context. 

DESCRIPTION 

LIB$FIND_FILE_END should be called by your program after each sequence 
of calls to LIB$FIND—FILE. This will prevent the default values from the 
previous call from affecting the next file specification. 

LIB$FIND_FILE_END deallocates the context used in the last call to 
LIB$FIND_FILE so that the context retained will not be used in subsequent 
calls to LIB$FIND_FILE. If LIB$FIND_FILE was directed to process file 
specifications for multiple input files, the saved file specifications are also 
deallocated. 

CONDITION 

VALUES 

RETURNED 

RMS$_NORMAL Procedure successfully completed. 

RMS$_FAB File access block argument is not the address of a 

valid FAB. 
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LIB$FIIMD—IMAGE-SYMBOL—Find Universal 
Symbol in Shareable Image File 


LIB$FIND_IMAGE_SYMBOL reads universal symbols from the 
shareable image file. This routine then dynamically activates a 
shareable image into the PO address space of a process. 

FORMAT 

LIB$FIND_IMAGE_SYMBOL filename 

symbol-desc 

,symbol-val 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


filename 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the file for which LIB$FIND_IMAGE—SYMBOL is searching. The 
filename argument is the address of a descriptor pointing to this file name 
string. This argument may contain only the file name. File type cannot 
be indicated. If any file specification punctuation characters (:, [, <, .) are 
present, the error SS$_IVLOGNAM is returned. 


A default file specification of SYS$SHARE:.EXE is applied to the file name. If 
the file is not in SYS$SHARE:.EXE, a logical name must be used to direct this 
routine to locate the correct file. Only logical names defined in the system 
logical name table with the /EXEC attribute will be considered while the 
image activator is processing a request from an image that was installed with 
privileges. If the calling image was installed with privileges, the image being 
activated must also be installed with privileges. 


symbol-desc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Symbol for which LIB$FIND_IMAGE—SYMBOL is searching in the filename 
file. The symbol-desc argument is the address of a descriptor pointing to 
the symbol name string. The symbol name string must be input in uppercase 
letters; this routine does not perform uppercase conversion. 
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symbol-val 

VMS Usage: longword_signed 
type: longword (signed) 

access: write only 

mechanism: by reference 

Symbol value that LIB$FIND_IMAGE—SYMBOL has located. The symbol- 
val argument is the address of a signed longword integer into which 
LIB$FIND_IMAGE—SYMBOL returns the symbol value. If the symbol is 
relocatable, the starting virtual address of the shareable image in memory will 
be added to the symbol value. 


DESCRIPTION The shareable image that LIB$FIND_IMAGE—SYMBOL activates must have 

been already linked and must be position independent. You must have read 
access to the shareable image file to use this routine. 

LIB$FIND_IMAGE—SYMBOL locates the universal symbol in its database 
without first processing the filename argument. Due to this fact, a reference 
to a lexically different file name causes a new copy of the same shareable 
image to be loaded and searched. To avoid this situation, always specify the 
desired file name in the same form. 

LIB$FIND_IMAGE—SYMBOL writes the symbol value that it has located into 
the symbol-val argument. 

After the first call to LIB$FIND_IMAGE—SYMBOL for a particular image, 
successive calls for that image will be processed quickly. The image is 
activated only once and an in-memory database is maintained. There is no 
way to deallocate this database, nor is there any supported method to remove 
an activated image from the address space. All images are activated into PO 
space. 

LIB$FIND_IMAGE—SYMBOL disables AST recognition while it is executing. 
AST recognition is reenabled before returning to the caller only if AST 
recognition was previously enabled. 

LIB$FIND_IMAGE—SYMBOL signals all errors as well as returning the status 
in RO. 


CONDITION 

LIB$_BADCCC 

Illegal compilation code. 

VALUES 

LIB$_EOMERROR 

Compilation errors. 

RETURNED 

LIB$_EOMF AT AL 

Fatal compilation errors. 


LIB$_EOMWARN 

Compilation warnings. 


LIB$_GSDTYP 

Illegal universal symbol directory record type. 


LIB$_ILLFMLCNT 

Maximum argument count exceeds maximum for 
procedure. 


LIB$_ILLMODNAM 

Illegal module name length. 


LIB$_ILLPSCLEN 

Illegal program section length. 


LIB$_ILLRECLEN 

Illegal record length in module. 


LIB$_ILLRECLN2 

Illegal record length. 


LIB$_ILLRECTYP 

Illegal record type in module. 


LIB$_ILLRECTY2 

Illegal record type. 
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LIB$_ILLSYMLEN 
LIB$_NOEOM 
LIB$_RECT OOSML 

LIB$_SEQUENCE 

LIB$_SEQUENCE2 

LIB$_STRVL 

Note that all of the above 
error messages indicate 
a format error in the 
shareable image. 

LIB$_INSVIRMEM 

SS$_IVLOGNAM 


Illegal symbol length. 

No end of module record contained in the module. 

Record too small; data overflows object record in 
module. 

Illegal record sequence in module. 

Illegal record sequence. 

Illegal object language structure level in module. 


Insufficent virtual memory. 

The filename argument contained more than just 
a file name; a device or directory specification was 
found in the string. 


Any condition values returned by LIB$INSERT_TREE. 
Any condition values returned by RMS. 
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LIB$FIXUP_FLT—Fix Floating Reserved 



Operand 

LIB$FIXUP_FLT finds the reserved operand of any F_floating, 
D_floating, G_floating, or H_floating instruction (with some 
exceptions) after a reserved operand fault has been signaled. 
LIB$FIXUP_FLT changes the reserved operand from -0.0 to the 
value of the new-operand argument, if present; or to +0.0 if new- 
operand is absent. 

FORMAT 

LIB$FIXUP_FLT sig-args ,mch-args [,new-operand] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

sig-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Signal argument vector. The sig-args argument is the address of an an array 
of unsigned longwords containing the signal argument vector. 

mch-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Mechanism argument vector. The mch-args argument is the address of an 
array of unsigned longwords containing the mechanism argument vector. 

new-operand 

VMS Usage: floating-point 
type: F_floating 

access: read only 

mechanism: by reference 

An F__floating value to replace the reserved operand. The new-operand 
argument is the address of an F_floating number containing the new operand. 
This is an optional argument. If omitted, the default value is +0.0. 
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DESCRIPTION LIB$FIXUP_FLT cannot handle the following cases and will return a status of 

SS$_RESIGNAL if any of them occur: 

• The currently active signaled condition is not SS$_ROPRAND. 

• The reserved operand's data type is not F_floating, D_floating, G_ 
floating, or H_floating. 

• The reserved operand is an element in a POLYx coefficient table. 

If the status value returned from LIB$FIXUP__FLT is seen by the condition 
handling facility (as would be the case if LIB$FIXUP_FLT was the handler), 
any success value is equivalent to SS$_CONTINUE, which causes the 
instruction to be restarted. Any failure value is equivalent to SS$_ 
RESIGNAL, which causes the condition to be resignaled to the next handler. 
This resignal status is because the condition handler (LIB$FIXUP_FLT) was 
unable to handle the condition correctly. 

LIB$FIXUP_FLT can be enabled directly as a condition handler. The sig- 
args and mch-args arguments are passed to the condition handler by VMS 
exception dispatching. 


CONDITION 

VALUES 

RETURNED 

SSS—NORMAL 

SS$_ACCVIO 

Routine successfully completed. The reserved 
operand was found and has been fixed. 

Access violation. An argument to LIB$FIXUP_FLT 
or an operand of the faulting instruction could not 
be read or written. 


SS$_RESIGNAL 

The signaled condition was not SS$_ROPRAND, or 
the reserved operand was not a floating-point value 
or was an element in a POLYx table. 


SS$_ROPRAND 

Reserved operand fault. The optional argument 
new-operand was supplied but was itself an 
F_floating reserved operand. 


LIB$_BADSTA 

Bad stack. The stack frame linkage has been 
corrupted since the time of the reserved operand 
exception. 
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LIB$FLT_UNDER—Floating-Point 



Underflow Detection 

LIB$FLT_UNDER enables or disables floating-point underflow 
detection for the calling procedure activation. The previous setting 
is returned as a function value. 

FORMAT 

LIB$FLT_UNDER new-setting 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The old floating-point underflow enable setting (the previous contents of the 
SF$W_PSW[PSW$V_FU] in the caller's frame). 

ARGUMENT 

new-setting 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

New floating-point underflow enable setting. The new-setting argument is 
the address of an unsigned byte containing the new setting. Bit 0 set to 1 
means enable; bit 0 set to 0 means disable. 

DESCRIPTION 

LIB$FLT_UNDER affects only the current procedure activation and does 
not affect any of its callers or any procedures that it may call. However, the 
setting does remain in effect for any procedures entered through a JSB entry 
point. 

The caller's stack frame will be modified by this procedure. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


C+ 

C This FORTRAN example program illustrates 
C the use of LIB$FLT_UNDER. 

C- 

INTEGER*4 NEW.SETTING 
REAL*4 X , Y , Z 

NEW.SETTING = 0 
X = IE-20 

Y = 1E20 

CALL LIB$FLT_UNDER( NEW.SETTING ) 

TYPE First Case: This should not have an underflow exception* 
Z = X / Y 

TYPE *, 'If this lines prints then the underflow exception 
1 was disabled.' 

TYPE * 

NEW_SETTING « 1 
X = IE-20 

Y = 1E20 

CALL LIB$FLT_UNDER( NEW.SETTING ) 

TYPE * , 'Second Case: This should have an underflow exception 
1 and then stop.' 

Z = X / Y 

TYPE * , 'If this line prints, then the underflow exception 
1 was disabled.' 

c CALL EXIT 

END 


In this FORTRAN example, floating-point underflow detection is disabled the 
first time X is divided by Y. The second time, underflow detection is enabled, 
and the program stops because of the error generated. 
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LIB$FREE. 

_EF—Free Event Flag 


LIB$FREE_EF frees a local event flag previously allocated by 
LIB$GET_EF. LIB$FREE_EF is the complement of LIB$GET_EF. 

FORMAT 

LIB$FREE_EF event-flag-num 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

event-flag-num 

VMS Usage: ef_number 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Event flag number to be deallocated by LIB$FREE_EF. The event-flag-num 
argument is the address of a signed longword integer that contains the event 
flag number, which is the value returned to the user by LIB$GET_EF. 

DESCRIPTION 

When a local event flag allocated by calling LIB$GET_EF is no longer needed, 
LIB$FREE_EF should be called to free the event flag for use by other routines. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_EF_ALRFRE Event flag already free. 

LIB$_EF_RESSYS Event flag reserved to system. This error occurs if 

the event flag number is outside the ranges of 1 to 

23 and 32 to 63. 

EXAMPLE 

For an example of using LIB$FREE_EF, see the example under LIB$GET_EF. 
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LIBSFREE- 

-LUN—Free Loaical Unit Number 

LIB$FREE_LUN releases a logical unit number allocated by LIB$GET_ 
LUN to the pool of available numbers. LIB$FREE_LUN is the 
complement of LIB$GET_LUN. 

FORMAT 

LIB$FREE_LUN log-unit-num 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

log-unit-num 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Logical unit number to be deallocated. The log-unit-num argument is the 
address of a signed longword integer that contains this logical unit number, 
which is the value previously returned by LIB$GET_LUN. 

DESCRIPTION 

When a logical unit number allocated by calling LIB$GET_LUN is no longer 
needed, it should be released for use by other routines. 

This routine is useful only in BASIC or FORTRAN programs. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_LUNALRFRE Logical unit number is already free. 

LIB$_LUNRESSYS Logical unit number reserved to system. This 

occurs if the specified logical unit number is outside 
the range of 100 to 119. 

EXAMPLE 

For an example of using LIB$FREE_LUN, see the example which appears 
under LIB$GET_LUN. 
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LIB$FREE_ 

.TIMER—Free Timer Storage 

LIB$FREE_TIMER frees the storage allocated by LIB$INIT_TIMER. 

FORMAT 

LIB$FREE_TIMER handle-adr 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

handle-adr 

VMS Usage: address 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Pointer to a block of storage containing the value returned by a previous call 
to LIB$INIT_TIMER; this is the storage that LIB$FREE_TIMER deallocates. 
The handle-adr argument is the address of an unsigned longword integer 
containing that value. 

DESCRIPTION 

LIB$FREE_TIMER frees a block of storage previously allocated by LIB$INIT_ 
TIMER. LIB$FREE_TIMER assumes that handle-adr was returned by a 
previous call to LIB$INIT_TIMER. If the block referred to by handle-adr was 
not allocated by LIB$INIT_TIMER, LIB$FREE_TIMER returns an error. If the 
routine completes successfully, LIB$FREE_TIMER sets handle-adr to zero. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument; handle-adr was not supplied or 

did not point to a timer block. 

LIB$_BADBLOADR Bad block address; LIB$FREE_VM could not 

deallocate the block to which handle-adr points. 
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LIB$FREE_VM—Free Virtual Memory from 

Program Region 

LIB$FREE_VM deallocates an entire block of contiguous bytes that 
were allocated by a previous call to LIB$GET_VM. The arguments 
passed are the same as for LIB$GET_VM. 


FORMAT 

LIB$FREE_VM num-bytes ,base-adr[,zone-id] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

num-bytes 


VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of contiguous bytes to be deallocated by LIB$FREE_VM. The num- 
bytes argument is the address of a signed longword integer that contains this 
number. The value of num-bytes must be greater than zero. 


Byte counts are rounded in the same manner as in LIB$GET_VM. 

Note: 

You may omit the num-bytes argument if you are using boundary tags 
(LIB$M—VM—BOUND ARY—T AGS). 


base-adr 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Address of the first byte to be deallocated by LIB$FREE_VM. The base-adr 
argument contains the address of an unsigned longword that is this address. 
The value of base-adr must be the address of a block of memory that was 
allocated by a previous call to LIB$GET—VM. 


zone-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The zone-id argument is the address of a longword that contains a zone 

identifier created by a previous call to LIB$CREATE_VM_ZONE or 

LIB$CREATE—USER—VM—ZONE. 
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You must specify the same zone-id value as when you called LIB$GET_VM 
to allocate the block. An error status will be returned if you specify an 
incorrect zone-id. The zone-id argument is optional. If zone-id is omitted or 
if the longword contains the value zero, LIB$VM's default zone is used. 

DESCRIPTION 

LIB$FREE_VM returns the block of memory to a free list associated with the 
zone, so the block is available on a subsequent call to LIB$GET_VM for the 
zone. 

The base-adr argument must contain the address of the first byte of memory 
that was allocated by a previous call to LIB$GET_VM. LIB$FREE_VM rounds 
up the value of num-bytes to a multiple of the block size for the zone. 


Note: You cannot free part of a block that was allocated by a call to LIB$GET_ 



VM. The whole block must be freed by a single call to LIB$FREE_VM. 

Neither can you combine contiguous blocks of memory that were 
allocated by several calls to LIB$GET_VM into one larger block that is 
freed by a single call to LIB$FREE_VM. 

If you specified deallocation filling when you created the zone, LIB$FREE_ 
VM will fill each byte freed. Note that part of a free block is used to store 
control information, so some bytes will not contain the fill value. 

LIB$FREE_VM is fully reentrant, so it can be called by procedures executing 
at AST-level or in an Ada multitasking environment. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_BADBLOADR Base-adr contained a bad block address. An 

address was outside of the area allocated by 
LIB$GET_VM / or the contents of base-adr were 
not properly aligned, or part of the space being 
deallocated was previously deallocated. 

LIB$_BADBLOSIZ Num-bytes is less than or equal to 0, or the num- 

bytes argument is incorrect for a zone containing 


fixed size blocks. 
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LIB$FREE_ 

-VM-PAGE—Free Virtual 


Memory Page 


LIB$FREE_VM_PAGE deallocates a block of contiguous pages that 
were allocated by previous calls to LIB$GET_VM_PAGE. 

FORMAT 

LIB$FREE_VM_PAGE num-pages , base-adr 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

num-pages 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of pages. The num-pages argument is the address of a longword 
integer which specifies the number of contiguous pages to be deallocated. 

The value of num-pages must be greater than zero. 


base-adr 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Block address. The base-adr argument is the address of a longword which 
contains the address of the first byte of the first page to be deallocated. 

DESCRIPTION 

LIB$FREE_VM__PAGE deallocates a block of contiguous pages starting at 
base-adr. Each of the pages specified by num-pages and base-adr must 
have been allocated by previous calls to LIB$GET_VM_PAGE. The pages are 
returned to the processwide page pool and are available to satisfy subsequent 
calls to LIB$GET_VM_PAGE. 


You can free a smaller group of pages than you allocated. That is, if you 
allocated a group of contiguous pages by a single call to LIB$GET_VM_ 
PAGE, you can deallocate those pages in several calls to LIB$FREE_VM_ 
PAGE. You can also combine contiguous groups of pages that were allocated 
in several calls to LIB$GET_VM_PAGE into one large group that is freed by 
a single call to LIB$FREE_VM_PAGE. 

LIB$FREE_VM_PAGE is fully reentrant, so it may be called by procedures 
executing at AST level or in an Ada multitasking environment. 
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CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

LIB$_BADBLOADR 

LIB$_BADBLOSIZ 


Normal successful completion. 

Pages not allocated by LIBSGET—VM—PAGE, the 
value of base-adr is not a page boundary, or the 
pages were previously freed. 

Num-pages is less than or equal to zero. 
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LIB$GET_COMMAND—Get Line from 

SYS$COMMAIMD 

LIB$GET_COMMAND gets one record of ASCII text from the 
current controlling input device, specified by the logical name 
SYSSCOMMAND. 


FORMAT 

LIBSGET 

.COMMAND 

get-str [, prompt-str] 

[, out-len] 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 



mechanism: 

by value 


ARGUMENTS 

get-str 

VMS Usage: 

char_string 



type: 

character string 



access: 

write only 



mechanism: 

by descriptor 



String that LIB$GET_COMMAND gets from SYS$COMMAND. The get-str 
argument is the address of a descriptor pointing to this string. 


prompt-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Prompt message that LIB$GET_COMMAND displays on the controlling 
terminal. The prompt-str argument is the address of a descriptor pointing to 
the prompt. A valid prompt consists of text followed by no carriage-return 
/line-feed combination. A colon(:) and one space are optional. 


out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of bytes written into get-str by LIB$GET_COMMAND, not counting 
padding in the case of a fixed string. The out-len argument is the address 
of an unsigned word containing this length. If the input string is truncated 
to the size specified in the get-str descriptor, out-len is set to this size. 
Therefore, out-len can always be used by the calling program to access a 
valid substring of get-str. 
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DESCRIPTION LIB$GET_COMMAND uses the VAX RMS $GET service (see the VAX Record 

Management Services Reference Manual) to get one record of ASCII text from 
the current controlling input device, specified by SYS$COMMAND. 

When you log in, VAX/VMS creates three files as default I/O control streams 
for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between 
your interactive input and output or your batch commands and the VAX/VMS 
software. Initially, all three are equated with the terminal. However, with 
the DCL ASSIGN command, you can change these assignments to obtain 
information from a file or put information into a file. SYS$INPUT and 
SYSSCOMMAND are usually identical, but the input and command streams 
can be different. For example, during the execution of an indirect command 
file from an interactive terminal, SYS$COMMAND refers to the terminal and 
SYS$INPUT refers to the command file. 

LIB$GET_COMMAND opens file SYS$COMMAND on the first call. The 
VAX RMS internal stream identifier (ISI) is stored in the procedure's static 
storage for subsequent calls. 

If prompt-str is provided and if the SYS$COMMAND device is a terminal, 
LIB$GET_COMMAND displays the prompt message. If the device is not a 
terminal, the prompt-str is ignored. 

LIB$GET_COMMAND is used when a program needs input from some 
source other than the current input stream. Usually, it is used to input 
from the terminal rather than from an indirect command file. For example, 
a program may ask a question which cannot be answered by an indirect 
command file entry. In this case the program would call LIB$GET_ 
COMMAND to get one record of ASCII text from SYS$COMMAND, the 
terminal. 


CONDITION SS$_NORMAL 

VALUES 

RETURNED lib$_faterrlib 


LIB$_INPSTRTRU 


LIB$_JNSVIRMEM 


Routine successfully completed. VAX RMS 
completion status. 

An internal consistency check on Run-Time Library 
data structures has failed. This may indicate a 
programming error in the Run-Time Library, or that 
your program may have overwritten those data 
structures. 

The input string has been truncated to the size 
specified in the get-str descriptor (fixed-length 
strings only). Out-len is also set to this size. This 
is an error (as opposed to LIB$_STRTRU which 
is a success) because the truncation is not under 
program control. 

Insufficient virtual memory to allocate the dynamic 
string. 
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LIB$_INVARG Invalid arguments. The descriptor class field is not 

a recognized code or is zero. 


Any valid RMS status code. 

Any code returned by LIB$GET_VM or LIB$SCOPY_R_DX. 
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LIB$GET_COMMON—Get String from 

Common 



LIB$GET_COMMON copies a string in the common area to the 
destination string. (The common area is an area of storage which 
remains defined across multiple image activations in a process.) The 
string length is taken from the first longword of the common area. 

FORMAT 

LI B$G ET—COMMO N dst-str[,chars-copied] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$GET_COMMON writes the string copied 
from the common area. The dst-str argument is the address of a descriptor 
pointing to the destination string. 

chars-copied 

VMS Usage: word_signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of characters written into dst-str by LIB$GET_COMMON, not 
counting padding in the case of a fixed-length string. The chars-copied 
argument is the address of a signed word integer containing the number of 
characters copied. If the input string is truncated to the size specified in the 
dst-str descriptor, chars-copied is set to this size. Therefore, chars-copied 
can always be used by the calling program to access a valid substring of 
dst-str. 

DESCRIPTION 

LIB$PUT_COMMON allows a program to copy a string into the process's 
common storage area. This area remains defined during multiple image 
activations. LIB$GET_COMMON allows a program to copy a string from the 
common area into a destination string. The programs reading and writing the 
data in the common area must agree upon its amount and format. 

The maximum number of characters that can be copied is 252. The 
actual number of characters copied is returned by the optional argument, 
chars-copied (if given). 
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CONDITION 

VALUES 

RETURNED 


You can use LIB$PUT_COMMON and LIB$GET_COMMON to pass 
information between images run successively, such as chained images run by 
LIB$RUN_PROGRAM. 


SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Routine successfully completed. 

Successfully completed. The string was longer 
than the buffer and was truncated. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$GETDVI—Get Device/Volume 

Information 


LIB$GETDVI provides a simplified interface to the $GETDVI system 
service. It returns information about the primary and secondary 
device characteristics of an I/O device. The calling process need 
not have a channel assigned to the device about which it wants 
information. 

FORMAT 

LI B$G ETDVI item-code [, channel] [,device-name] 

[, out-value] [, out-string] [, out-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


item-code 


VMS Usage: 
type: 
access: 
mechanism: 


longword_signed 
longword integer (signed) 
read only 
by reference 


Code specifying the item of information you are requesting. The item-code 
argument is the address of a signed longword integer containing the item 
code. All valid $GETDVI item codes, whose names begin with DVI$_, are 
accepted. 


See the Description section for more information on item codes. 


channel 

VMS Usage: channel 
type: word (unsigned) 

access: read only 

mechanism: by reference 

VMS I/O channel assigned to the device for which LIB$GETDVI returns 
information. The channel argument is the address of an unsigned word 
containing the channel specification. If channel is not specified, device-name 
is used instead. You must specify either channel or device-name, but 
not both. If both or neither is specified, the error status LIB$_INVARG is 
returned. 


device-name 

VMS Usage: device_name 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the device for which LIB$GETDVI returns information. The device¬ 
name argument is the address of a descriptor pointing to the device name 
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string. If this string contains a colon, the colon and the characters that follow 
it are ignored. 

The device-name may be either a physical device name or a logical name. 

If the first character in the string is an underscore character the name 
is considered a physical device name. Otherwise, the name is considered a 
logical name, and logical name translation is performed until either a physical 
device name is found or the system default number of translations has been 
performed. 

If device-name is not specified, channel is used instead. You must specify 
either channel or device-name, but not both. If both or neither is specified, 
the error status LIB$__INVARG is returned. The device name must not be 
longer than 255 characters. 


out-value 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Numeric value of the information requested. The out-value argument is the 
address of an unsigned longword containing the numeric value. If an item is 
listed as only returning a string value, this argument is ignored. 

out-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String representation of the information requested. The out-string argument 
is the address of a descriptor pointing to this information. If out-string is not 
specified and if the value returned has only a string representation, the error 
status LIB$_INVARG is returned. 

Refer to Table RTL-4 for descriptions of the string representations used for 
each item. 


out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of significant characters written to out-string by LIB$GETDVI. The 
out-len argument is the address of an unsigned word containing this length. 


DESCRIPTION LIB$GETDVI returns two categories of information. 

• Primary device characteristics 

• Secondary device characteristics 

LIB$GETDVI does not allow you to get more than one item of information in 
a single call. 


RTL-145 





Run-Time Library Routines 

LIB$GETDVI 


LIB$GETDVI provides the following features in addition to those provided by 
the $GETDVI system service. 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 

• For items which return numeric values, LIB$GETDVI can optionally 
provide a formatted string interpretation of the value. For example, if the 
device owner UIC is requested, LIB$GETDVI can return the UIC formatted 
as "[identifier]". 

• For string arguments, LIB$GETDVI understands all string classes 
supported by the Run-Time Library. 

• Calls to LIB$GETDVI are synchronous; LIB$GETDVI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

See the description of the $GETDVI system service in the VAX/VMS System 
Services Reference Manual for more detailed information. 

Item Codes 

All item codes that can be used with the $GETDVI system service may be 
used as the item-code argument to LIB$GETDVI. These codes have symbolic 
names beginning with DVI$_ 

The use of a DVI$_ code by itself will return the primary device characteristic 
associated with that code. To obtain the secondary device characteristics, 
add 1 to the code. See the description of the $GETDVI system service for 
a list of the defined item codes. The symbolic names for these items are 
defined in DIGITAL-supplied symbol libraries in module $DVIDEF (where 
appropriate). 

Value Formats 

By using the out-value and out-string arguments to LIB$GETDVI, the 
information requested can be returned in two different fashions. 

• For those items described as "string" in the table of Item Identifier Codes 
for the $GETDVI service, the value is returned in out-string only; out¬ 
value is ignored and the alternate success status LIB$_STRVALITE is 
returned. 

• For all other items, those which have a numeric value, the numeric 
representation is returned in out-value (if specified), and a formatted 
string interpretation of the value is returned in out-string. 

Each formatted item is written left-justified; out-len, if specified, gives the 
number of characters used. Table RTL-4 lists the formats used for the string 
interpretations. 

Table RTL-4 Formats used for LIB$GETDVI Strings 

Item or Format Description 

DVI$_ACPPID The string value is returned as an 8-digit hexadecimal number. 

DVI$_PID The string value is returned as an 8-digit hexadecimal number. 
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Table RTL-4 (Cont.) Formats used for LIB$GETDVI Strings 


Item or Format 

Description 

DVI$_ACPTYPE 

The ACP type string is one of the following: 

NONE No ACP 

F11VI Files-11 Level 1 

F11V2 Files-11 Level 2 

MTA Magnetic Tape 

NET Networks 

REM Remote I/O 

JNL Journal 

DVI$_OWNUIC 

The standard UIC format of [group,member] is used. If the 
format of a UIC includes identifiers from the access rights 
database in place of the octal group and member numbers, the 
UIC string returned will have these identifiers, if available. 

DVI$_VPROT 

The volume protection string is in the form: 

SYSTEM=RWLP,OWNER=RWLP,GROUP=RWLP,WORLD=RWLP 

If a category has no access, the equals sign is omitted. The 
string will not contain any embedded spaces. 

Boolean 

The value string returned is TRUE if the low bit of the value is 
set, or FALSE if the low bit is clear. 

All others 

The value string is returned in the form of an unsigned decimal 
integer. 


CONDITION SS$_NORMAL 

VALUES LIB$_STRVALITE 

RETURNED 

LIB$_INSEF 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_UNRITECOD 

LIB$_WRONUMARG 


Routine successfully completed. 

String-valued item. This is an alternate success 
status. The value of the item returned has only 
a string value. If out-value was specified, it was 
ignored. 

Insufficient event flags. A local event flag number 
could not be allocated by a call to LIB$GET_EF. 

Invalid argument. Neither channel nor device- 
name was specified, or both were specified. 

Invalid string descriptor. The descriptor for a string 
parameter was not a valid string descriptor. 

Unrecognized item code. Item-code was not 
recognized as valid by SGETDVI or LIB$GETDVI. 

Wrong number of arguments. An incorrect number 
of arguments was passed to LIBSGETDVI. 


Condition values returned by LIB$SCOPY_xxx are returned by LIB$GETDVI. 
Truncation errors are ignored. 

Any condition value returned by SYS$GETDVI. 
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LIB$GET_ 

.EF—Get Event Flag 


LIB$GET_EF allocates one local event flag from a process-wide pool 
and returns the number of the allocated flag to the caller. If no flags 
are available, LIB$GET_EF returns an error as its function value. 

FORMAT 

LIB$GET_EF event-flag-num 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

event- flag-num 

VMS Usage: ef_number 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Number of the local event flag that LIB$GET_EF allocated, or -1 if no local 
event flag was available. The event-flag-num argument is the address of a 
signed longword integer into which LIB$GET_EF writes the number of the 
local event flag that it allocates. 


DESCRIPTION LIB$GET_EF and LIB$FREE_EF cause local event flags to be allocated and 

deallocated at run time, so that your procedure remains independent of other 
procedures executing in the same process. 


The following table lists status of local event flags. 


Number Status 

0 Never used by this procedure and always available 

1-23 Initially reserved; available after being freed by LIB$FREE_EF 

24-31 Reserved to VAX/VMS 

32-63 Initially free 


Local event flags numbered 32 to 63 are available to your program. 

These event flags allow procedures to communicate and synchronize their 
operations. 

Using LIB$GET_EF provides your program with an arbitrary event 
flag number. You can obtain a specific event flag number by calling 
LIB$RESERVE_EF. and passing as an argument the number of the specific 
event flag that you wish to reserve. However, reserving a specific local event 
flag number is not recommended. If you use a specific event flag in your 
procedure, another procedure may attempt to use the same flag, and the flag 
will no longer function as expected. Therefore, you should call LIB$GET_JEF 
to obtain the next arbitrary event flag and LIB$FREE_EF to return it to the 
storage pool. 
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CONDITION SS$_NORMAL 
VALUES LIB$_INSEF 

RETURNED 


Procedure successfully completed. 

Insufficient event flags. There were no more event 
flags available for allocation. 
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LIB$GET_FOREIGN—Get Foreign 

Command Line 

LIB$GET_FOREIGN requests the calling image's Command Language 
Interpreter (CLI) to return the contents of the "foreign command" line 
that activated the current image. 


FORMAT LIB$GET_FOREIGN get-str[,user-prompt][,out-len] 

[, force-prompt] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


get-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 

String which LIB$GET_FOREIGN uses to receive the foreign command 
line. The get-str argument is the address of a descriptor pointing to this 
string. If the foreign command text returned was obtained by prompting to 
SYS$INPUT (see the description of force-prompt), the text is translated to 
uppercase so as to be more consistent with text returned from the CLI. 


user-prompt 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Optional user-supplied prompt for text which LIB$GET_FOREIGN uses if no 
command-line text is available. The user-prompt argument is the address 
of a descriptor pointing to the user prompt. If omitted, no prompting is 
performed. It is recommended that user-prompt be specified. If user-prompt 
is omitted and if no command-line text is available, a zero-length string will 
be returned. 


out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of bytes written into get-str by LIB$GET_FOREIGN, not counting 
padding in the case of a fixed-length get-str. The out-len argument is the 
address of an unsigned word into which LIB$GET_JFOREIGN writes the 
number of bytes. 
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force-prompt 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: modify 

mechanism: by reference 

Value which LIB$GET_FOREIGN uses to control whether or not prompting 
is to be performed. The force-prompt argument is the address of a signed 
longword integer containing this value. If the low bit of force-prompt is zero, 
or if force-prompt is omitted, prompting is done only if the CLI does not 
return a command line. If the low bit is 1, prompting is done unconditionally. 
If specified, force-prompt is set to 1 before returning to the caller. 


The primary use of force-prompt is to allow a utility program to be invoked 
once with subcommand text on the command line, and then to repeatedly 
prompt for further subcommands from SYS$INPUT. This is accomplished 
by calling LIB$GET_FOREIGN repeatedly, specifying in the call a user- 
prompt string and a force-prompt variable which is initialized to zero at the 
beginning of the program. The first call gets the subcommand text from the 
command line, after which force-prompt will be set to 1, causing further 
subcommands to be requested through prompts to SYS$INPUT. 


DESCRIPTION LIB$GET__FOREIGN returns the contents of the command line that you 

use to activate an image. It can be used to give your program access to the 
qualifiers of a foreign command or to prompt for further command line text. 

A foreign command is a command that you can define and then use as if it 
were a DCL or MCR command in order to run a program. When you use the 
foreign command at command level, the CLI parses the foreign command 
only and activates the image. It ignores any options or qualifiers that you 
have defined for the foreign command. Once the CLI has activated the image, 
the program can call LIB$GET_FOREIGN to obtain and parse the remainder 
of the command line (after the command itself) for whatever options it may 
contain. See the VAX/VMS DCL Dictionary for information on how to define 
a foreign command. 

If no command line is available, LIB$GET_FOREIGN can optionally 
call LIB$GET_INPUT to prompt the user for command text. If desired, 
LIB$GET_FOREIGN can be called repetitively, returning the command line 
on the first call, but prompting for further text on subsequent calls. 

LIB$GET_FOREIGN can also be used for images invoked by the RUN 
command, for which further text must be obtained by prompting. Such 
an image can also be invoked by the DCL command MCR or by the MCR 
Command Language Interpreter. The text following the image name will be 
returned to the executing image. 
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The action of LIB$GET_FOREIGN depends on the environment in which the 

image is activated. 

• If you use a foreign command to invoke the image, you can call 
LIB$GET_FOREIGN to obtain the command qualifiers following the 
foreign command. You can also use LIB$GET_FOREIGN to prompt 
repeatedly for more qualifiers after the command. This technique is 
illustrated in the example. 

• If the image is in the SYS$SYSTEM: directory, the image can be invoked 
by the DCL MCR command or by the MCR Command Language 
Interpreter. In this case, LIB$GET_FOREIGN returns the command line 
text following the image name. 

• If the image is invoked by a DCL RUN command, LIB$GET_FOREIGN 
can be used to prompt for additional text. 

• If the image is not invoked by a foreign command or MCR, or if there is 
no information remaining on the command line, and the user-supplied 
prompt is present, LIB$GET_INPUT is called to prompt for a command 
line. If the prompt is not present, LIB$GET_FOREIGN returns a zero 
length string. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_FATERRLIB 

LIB$_INPSTRTRU 


Procedure successfully completed. 

A fatal internal error was detected. 

The input string was truncated. Get-string could 
not contain all of the characters. Out-len reflects 
the truncated length. 

Insufficient virtual memory. 

Invalid string descriptor. 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


A condition value returned by RMS. SYS$INPUT was prompted for command 
text and RMS returned an error. The most typical error will be RMS$_EOF, 
end-of-file. 


EXAMPLE 


EXAMPLE: PROCEDURE OPTIONS (MAIN); 


^INCLUDE $STSDEF; /* Status-testing definitions */ 


DECLARE COMMAND.LINE CHARACTER(80) VARYING. 

PROMPT.FLAG FIXED BINARY(31) INIT(O). 
LIB$GET_FOREIGN ENTRY (CHARACTER^) VARYING. 


CHARACTER(*) VARYING. 
FIXED BINARY(15), 
FIXED BINARY(31)) 


OPTIONS(VARIABLE) RETURNS (FIXED BINARY(31)), 
RMS$_E0F GLOBALREF FIXED BINARY(31) VALUE; 


/* Repeat forever calling LIB$GET_FOREIGN to obtain 
subcommand text and print the text. Exit when an 
end-of-file is found. */ 
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DO WHILE ('1'B); /* Do while TRUE */ 
STS$VALUE = LIB$GET_FOREIGN 

(COMMAND.LINE,'Input: ' , , 
PROMPT.FLAG); 

IF STS$SUCCESS THEN 

PUT LIST (' Command was '.COMMAND.LINE); 
ELSE DO; 

IF STSIVALUE ~= RMS$_E0F THEN 
PUT LIST ('Error encountered'); 

RETURN; 

END; 

PUT SKIP; /* Skip to next line */ 

END; /* End oi DO WHILE loop */ 

END; 


This PL/I example illustrates the use of the optional force-prompt argument 
to permit repeated calls to LIB$GET_FOREIGN. The command line text will 
be retrieved on the first pass only; after this, the program will prompt from 
SYS$INPUT. 
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LIB$GET_INPUT—Get Line from 



SYS$INPUT 

LIB$GET_INPUT gets one record of ASCII text from the current 
controlling input device, specified by SYSSINPUT. 

FORMAT 

LI B$GET_I NPUT get-str [,prompt-str][, out-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

get-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String which LIB$GET_INPUT gets from the input device. The get-str 
argument is the address of a descriptor pointing to the character string into 
which LIB$GET_INPUT writes the text received from the current input 
device. 

prompt-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Prompt message that is displayed on the controlling terminal. The prompt- 
str argument is the address of a descriptor containing the prompt. A valid 
prompt consists of text followed by a colon (:), a space, and no carriage- 
retum/line-feed combination. The maximum size of the prompt message is 
255 characters. If the controlling input device is not a terminal, this argument 
is ignored. 

out-len 

VMS Usage: word_unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of bytes written into get-str by LIB$GET_INPUT, not counting 
padding in the case of a fixed string. The out-len argument is the address 
of an unsigned word containing this number. If the input string is truncated 
to the size specified in the get-str descriptor, out-len is set to this size. 
Therefore, out-len can always be used by the calling program to access a 
valid substring of get-str. 
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DESCRIPTION LIB$GET_INPUT uses the VAX RMS $GET service to get one record of ASCII 

text from the current controlling input device, specified by SYS$INPUT. (For 
more information about the VAX RMS $GET service see the VAX Record 
Management Services Reference Manual.) 

When you log in, VAX/VMS creates three files as default I/O control streams 
for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between 
your interactive input and output or your batch commands and the VAX/VMS 
software. Initially, all three names are equated with the terminal. However, 
with the DCL ASSIGN command, you can change these assignments to 
obtain information from a file or put information into a file. SYS$INPUT and 
SYS$COMMAND are usually identical, but the input and command streams 
can be different. For example, during the execution of an indirect command 
file from an interactive terminal, SYS$COMMAND refers to the terminal and 
SYS$INPUT refers to the command file. 

LIB$GET_INPUT opens file SYS$INPUT on the first call. The VAX RMS 
internal stream identifier (ISI) is stored in the procedure's static storage for 
subsequent calls. Hence, this procedure is not AST reentrant. 

If prompt-str is provided and the SYS$INPUT device is a terminal, LIB$GET_ 
INPUT displays the prompt message. If the device is not a terminal, the 
prompt-str argument is ignored. 

If you wish to get input from some source other than the current input 
stream, use LIB$GET_COMMAND. 


CONDITION SS$_NORMAL 

VALUES 

RETURNED lib$_faterrlib 

LIB$_INPSTRTRU 

LIB$_INSVIRMEM 

LIB$_INVARG 


Routine successfully completed. VAX RMS 
completion status. 

An internal consistency check on Run-Time Library 
data structures has failed. This may indicate a 
programming error in the Run-Time Library, or that 
your program may have overwritten those data 
structures. 

The input string has been truncated to the size 
specified in the get-str descriptor (fixed-length 
strings only). Out-len is also set to this size. This 
is an error (as opposed to LIB$_STRTRU which 
is a success) because the truncation is not under 
program control. 

Insufficient virtual memory to allocate the dynamic 
string. 

Invalid arguments. The descriptor class field is not 
a recognized code or is zero. 


Any RMS condition value returned by $GET. 

Any condition value returned by LIB$GET_VM or LIB$SCOPY_R_DX. 
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LIB$GETJPI—Get Job/Process 

Information 


LIB$GETJPI provides a simplified interface to the $GETJPI system 
service. It provides accounting, status, and identification information 
about a specified process. 

LIB$GETJPI obtains only one item of information in a single call. 

FORMAT 

LIB$GETJPI item-code [,process-id] 

[,process-name] [, out-value] 

[, out-string] [, out-len] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS item-code 


VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Item identifier code specifying the item of information you are requesting. 
The item-code argument is the address of a signed longword integer 
containing the item code. You may request only one item in each call to 
LIB$GETJPI. 


LIB$GETJPI accepts all $GETJPI item codes. These names begin with JPI$_ 

and are defined in DIGITAL-supplied symbol libraries in module $JPIDEF. 


process-id 

VMS Usage: process—id 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Process identification of the process for which you are requesting information. 
The process-id argument is the address of an unsigned longword containing 
the process identification. If you do not specify process-id, process-name is 
used. 

The process-id is updated to contain the process identification actually used, 
which may be different from what you originally requested if you specified 
process-name or used wildcard process searching. 
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process-name 

VMS Usage: process_name 
type: character string 

access: read only 

mechanism: by descriptor 

A 1- to 15-character string specifying the name of the process for which you 
are requesting information. The name must correspond exactly to the name 
of the process for which you are requesting information; LIB$GETJPI does not 
allow trailing blanks or abbreviations. 


If you do not specify process-name, process-id is used. If you specify neither 
process-name or process-id, the caller's process is used. 


out-value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Numeric value of the information you requested. The out-value argument 
is the address of a longword or quadword into which LIB$GETJPI writes the 
numeric value of this information. Refer to Table RTL-5 for information on 
which items return longword values and which return quadword values. If 
the item you requested returns only a string value, this argument is ignored. 


out-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String representation of the information you requested. The out-string 
argument is the address of a character string into which LIB$GETJPI writes 
the string representation. Table RTL-5 describes the string representations 
used for each item. 


If you do not include out-string, but the item you request has only a string 
representation, the error status LIB$_INVARG is returned. 


out-len 


VMS Usage: 
type: 
access: 
mechanism: 


word—signed 
word integer (signed) 
write only 
by reference 


Number of significant characters written to out-string by LIB$GETJPI. 
The out-len argument is the address of a signed word integer into which 
LIB$GETJPI writes the number of characters. 


DESCRIPTION LIB$GETJPI provides the following features in addition to those provided by 

the $GETJPI system service. 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 
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• For items which return numeric values, LIB$GETJPI can optionally provide 
a formatted string interpretation of the value. For example, if the process 
UIC is requested, LIB$GETJPI can return the UIC formatted as "[g,m]". 

• For string arguments, all string classes supported by the Run-Time Library 
are understood. 

• Calls to LIB$GETJPI are synchronous. LIB$GETJPI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

See the description of the $GETJPI system service in the VAX/VMS System 
Services Reference Manual for more information. 

By using the out-value and out-string arguments to LIB$GETJPI, the 
information requested can be returned in two different fashions. For those 
items described as "string" in the table of Item Identifier Codes for the 
$GETJPI service, the value is returned in out-string only; out-value is 
ignored and the alternate success status LIB$_STRVALITE is returned. For all 
other items—those which have a numeric value—the numeric representation 
is returned in out-value (if specified), and a formatted string interpretation of 
the value is returned in out-string. 

Each formatted item is written left-justified; out-len, if specified, gives the 
number of characters used. For the items that return blank-padded strings— 
for example, JPI$_USERNAME—trailing blanks are removed. 

Table RTL-5 lists the formats used for the string interpretations. 


Table RTL-5 Item Code Formats for LIB$GETJPI 


Item or Format 
JPI$_AUTHPRIV 


JPI$_CURPRIV 

JPI$_IMAGPRIV 

JPI$_PROCPRIV 

JPI$_LOGINTIM 

JPI$_PID 


Description 

The string representation of these quadword privilege 
masks is a list of the names of each privilege that is 
enabled. The privilege names are in uppercase, and are 
separated by commas. 

Same as for JPI$AUTHPRIV. 

Same as for JPI$AUTHPRIV. 

Same as for JPISAUTHPRIV. 

The string representation of the quadword time is a 
standard absolute date-time string. 

The process identification string is an 8-digit hexadecimal 
number. 
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Table RTL-5 (Cont.) Item Code Formats for LIB$GETJPI 


Item or Format 

Description 

JPI$_STATE 

The process state string is one of the following: 

CEF Common event flag wait 


COM 

Computable 


COMO 

COM, outswapped 


CUR 

Current process 


COLPG 

Collided page wait 


FPG 

Free page wait 


HIB 

Hibernate wait 


HIBO 

HIB, outswapped 


LEF 

Local event flag wait 


LEFO 

LEF, outswapped 


MWAIT Mutex and misc. resource wait 


PFW 

Page fault wait 


SUSP 

Suspended 


SUSPO 

SUSP, outswapped 

JPI$_UIC 

The standard UIC format of [group,member] is used. 

If the format of a UIC includes identifiers from the 
access rights database in place of the octal group and 
member numbers, the UIC string returned will have these 
identifiers, if available. 

JPI$_MODE 

The current mode string is one of: BATCH, INTERACTIVE 
or NETWORK. 

All others 

The value string is returned in the form of an unsigned 
decimal integer. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

LIB$_INSEF 

LIB$_INVSTRDES 

SSS—BADPARAM 

LIB$_WRONUMARG 


Routine successfully completed. 

Insufficient event flags. A local event flag number 
could not be allocated by a call to LIB$GET_EF. 

Invalid string descriptor. The descriptor for a string 
argument was not a valid string descriptor. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETJPI or LIB$GETJPI. 

Wrong number of arguments. An incorrect number 
of arguments was passed to LIB$GETJPI. 


Any condition value returned by LIB$SCOPY_xxx; truncation errors are 
ignored. 

Any condition value returned by SYS$GETJPI. 
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LIB$GET_ 

LUN—Get Logical Unit Number 


LIB$GET_LUN allocates one logical unit number from a process¬ 
wide pool. If a unit is available, its number is returned to the caller. 
Otherwise, an error is returned as the function value. 

FORMAT 

LIB$GET_LUN log-unit-num 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

log-unit-num 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Allocated logical unit number or -1 if none was available. The log-unit-num 
argument is the address of a longword into which LIB$GET_LUN returns the 
value of the allocated logical unit. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_INSLUN Insufficient logical unit numbers. No logical unit 

numbers were available. 


EXAMPLE 


PROGRAM LOGICAL_UNIT_NUM(INPUT, OUTPUT); 

{♦> 

< This program demonstrates how to allocate a logical 
{ unit number using LIB$GET_LUN and then deallocate 
{ the logical unit number using LIB$FREE_LUN. 

{-> 

PROCEDURE LIB$GET_LUN(%REF LOG.UNIT.NUM : INTEGER); EXTERN; 
PROCEDURE LIB$FREE_LUNC/.REF LOG.UNIT.NUM : INTEGER); EXTERN; 

VAR 

UNIT.NUMBER : INTEGER; 

BEGIN 

LIB$GET_LUN(UNIT_NUMBER); 

WRITELNC'The logical unit number allocated was: ',UNIT_NUMBER); 
LIB$FREE_LUN(UNIT.NUMBER); 

END. 


The output generated by this PASCAL example program is as follows: 

The logical unit number allocated was: 119 
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LIB$GETSYI—Get System-Wide 



Information 

LIB$GETSYI provides a simplified interface to the $GETSYI 
system service. The $GETSYI system service obtains status 
and identification information about the system. LIB$GETSYI 
returns only one item of information in a single call. 

FORMAT 

LI B$GETSYI item-code [, out-value][, out-string] 

[, out-len] [, csid] [, node-name] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

item-code 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Item code specifying the desired item of information. The item-code 
argument is the address of a signed longword integer containing this item 
code. All valid $GETSYI item codes are accepted. 

out-value 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Numeric value returned by LIB$GETSYI. The out-value argument is the 
address of a longword or quadword containing this value. If an item is listed 
as returning only a string value, this argument is ignored. 

out-string 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Information returned by LIB$GETSYI. The out-string argument is the 
address of a descriptor pointing to the character string that will receive this 
information. 

See the Description section for more information about value formats. 

If out-string is not specified and if the returned value has only a string 
representation, the error status LIB$_INVARG is returned. 
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out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Number of significant characters written to out-string, not including blank 
padding or truncated characters. The out-len argument is the address of an 
unsigned word into which LIB$GETSYI returns this number. 


csid 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Cluster system identification (CSID) of the node for which information is to 
be returned. The csid argument is the address of this CSID. If both csid and 
node-name are specified, LIB$GETSYI uses node-name and writes into the 
csid argument the CSID corresponding to the node identified by node name. 


The csid of a VAX node is assigned by the cluster-connection software and 
may be obtained by the DCL command SHOW CLUSTER. The value of the 
csid for a VAX node is not permanent; a new value is assigned to a VAX 
node whenever it joins or rejoins the VAXcluster. 


If csid is specified as -1, LIB$GETSYI assumes a wildcard operation and 
returns the requested information for each VAX node in the cluster, one node 
per call. 

If csid is not specified, node-name is used. 

node-name 


VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 


Name of the node for which information is to be returned. The node-name 
argument is the address of a descriptor pointing to the node name string. 

If node-name is not specified, csid is used. If neither node-name nor 
csid is specified, the caller's node is used. See the csid argument for more 
information. 


The node name string must contain from 1 to 15 characters and must 
correspond exactly to the VAX node name; no trailing blanks or abbreviations 
are permitted. 


DESCRIPTION LIB$GETSYI provides the following features in addition to those provided by 

the $GETSYI system service: 

• Instead of a list of item descriptors, which may be difficult to construct in 
high-level languages, the single item desired is specified as an integer code 
which is passed by reference. Results are written to separate arguments. 

• For items which return numeric values, LIB$GETSYI can optionally 
provide a formatted string interpretation of the value. 
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CONDITION 

VALUES 

RETURNED 


• For string arguments, all string classes supported by the Run-Time Library 
are understood. 

• Calls to LIB$GETSYI are synchronous. LIB$GETSYI calls LIB$GET_EF to 
allocate a local event flag number for synchronization. 

All item codes that can be used with the $GETSYI system service may be 
used as the item-code argument to LIB$GETSYI. See the description of the 
$GETSYI system service for a list of the defined item codes. Note that the 
symbolic names for these items are defined in DIGITAL-supplied symbol 
libraries in module $SYIDEF (where appropriate). 

Value Formats 

By using the out-value and out-string arguments to LIB$GETSYI, the 
information requested can be returned in two different fashions. For those 
items described as "string" in the table of Item Identifier Codes for the 
$GETSYI service, the value is returned in out-string only; out-value is 
ignored and the alternate success status LIB$_STRVALITE is returned. For all 
other items, those which have a numeric value, the numeric representation 
is returned in out-value (if specified), and an unsigned decimal integer 
representation is stored in out-string. 

Each formatted item is written left-justified; out-len, if specified, gives the 
number of characters used. For those items which return blank-padded 
strings, such as SYI$_VERSION, trailing blanks are removed. 

See the VAX/VMS System Services Reference Manual for a description of the 
$GETSYI system service. 


SS$_NORMAL 

LIB$_INSEF 

LIB$_INVSTRDES 

LIB$_STRVALITE 

LIB$_UNRITECOD 

LIB$_WRONUMARG 


Routine successfully completed. 

Insufficient event flags. A local event flag number 
could not be allocated by a call to LIB$GET_EF. 

Invalid string descriptor. The descriptor of the 
out-string argument is not a valid descriptor. 

String-valued item. This is an alternate success 
status. The value of the returned item has only 
a string value. If out-value was specified, it was 
ignored. 

Unrecognized item code. Item-code was not 
recognized as valid by $GETSYI or LIBSGETSYI. 

Wrong number of arguments. An incorrect number 
of arguments was passed to LIB$GETSYI. 


Any condition values returned by LIB$SCOPY_xxx; truncation errors are 
ignored. 

Any condition values returned by the $GETSYI system service. 
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LIB$GET_SYMBOL—Get Value of CLI 

Symbol 

LIB$GET_SYMBOL requests the calling process's Command 
Language Interpreter (CLI) to return the value of a CLI symbol as 
a string. LIB$GET_SYMBOL then returns the string to the caller. 
Optionally, LIB$GET_SYMBOL can return the length of the returned 
value and the table in which the symbol was found. 


FORMAT 

LIBSGET 

-SYMBOL symbol,ret-buf[,ret-len] 



[, tbl-ind] 

RETURNS 

VMS Usage: 

cond_value 

type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS 


symbol 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the symbol for which LIB$GET_SYMBOL searches. The symbol 
argument is the address of a descriptor pointing to the name of the symbol. 
LIB$GET_SYMBOL converts the symbol name to uppercase and removes 
trailing blanks before the search. Symbol must begin with a letter or dollar 
sign ($). The maximum length of symbol is 255 characters. 




ret-buf 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Value of the returned symbol. The ret-buf argument is the address of a 
descriptor pointing to a character string into which LIB$GET_SYMBOL writes 
the value of the symbol. 


ret-len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Length of the symbol value returned by LIB$GET_SYMBOL. The ret-len 
argument is the address of a signed word integer into which LIB$GET- 
SYMBOL writes the length. 
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tbl-ind 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference 

Indicator of which table contained the symbol. The tbl-ind argument is the 
address of a signed longword integer into which LIB$GET_SYMBOL writes 
the table indicator. 


Possible values of the table indicator are listed below. 


Symbolic Name 

Value 

Table 

LIB$K_CLI_LOCAI_SYM 

1 

Local symbol table 

LIB$K_CLI_GLOBAI_SYM 

2 

Global symbol table 


LIB$K_CLL_LOCAl^SYM and LIB$K_CLI_GLOBAL_SYM are defined in 
DIGITAL-supplied symbol libraries (macro or module name $LIBCLIDEF) and 
as global symbols. 


DESCRIPTION LIB$GET_SYMBOL first searches the local symbol table for the symbol name, 

then searches the global symbol table. Numeric values are converted to an 
ASCII representation of a signed decimal number before being returned. 

LIB$GET_SYMBOL is supported for use with the DCL Command Language 
Interpreter. If used with the MCR CLI, the error status LIB$_NOCLI will be 
returned. 

If an image is run directly as a subprocess or as a detached process, there is 
no CLI present to get the symbol. In that case, LIB$GET_SYMBOL returns 
the error status LIB$_NOCLI. 


CONDITION SS$_NORMAL 
VALUES LIB$_STRTRU 

RETURNED 

LIB$_FATERRLIB 


LIB$_INSCLIMEM 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Procedure successfully completed; string truncated. 
The destination string could not contain all the 
characters in the symbol value. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient CLI memory. The CLI could not obtain 
enough virtual memory to perform the function. 
This may be caused by having too many symbols 
defined. Deleting some symbol definitions may 
relieve the situation. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$_INVSYMNAM 

LIB$_NOCLI 


LIB$_NOSUCHSYM 

LIB$_UNECLIERR 


Invalid symbol name. The symbol name contained 
more than 255 characters or did not begin with a 
letter or dollar sign ($). 

No CLI present. The calling process did not have 
a CLI to perform the function or the CLI did not 
support the request type. Note that an image run 
as a subprocess or detached process does not 
have a CLI. 

No such symbol. The symbol was not defined in 
either the local or global symbol table. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL Command Language 
Interpreter, please report the problem to DIGITAL 
in a Software Performance Report (SPR). 
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LIB$GET_VM—Allocate Virtual Memory 



LIB$GET_VM allocates a specified number of contiguous bytes in 
the program region and returns the virtual address of the first byte 
allocated. 

FORMAT 

LIB$GET_VM num-bytes, base-adr [,zone-id] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

num-bytes 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of contiguous bytes that LIB$GET_VM allocates. The num-bytes 
argument is the address of a longword integer containing the number 
of bytes. LIB$GET_VM allocates enough memory to satisfy the request. 

Your program should not reference an address before the first byte address 
allocated (base-adr) or beyond the last byte allocated (base-adr + num-bytes 
- 1) since that space may be assigned to another procedure. The value of 
num-bytes must be greater than zero. 

base-adr 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

First virtual address of the contiguous block of bytes allocated by LIB$GET_ 
VM. The base-adr argument is the address of an unsigned longword 
containing this base address. 

zone-id 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The zone-id argument is the address of a longword that contains a zone 
identifier created by a previous call to LIB$CREATE_VM_ZONE or 
LIB$CREATE_USER_VM—ZONE. This argument is optional. If zone-id 
is omitted or if the longword contains the value 0, LIB$VM's default zone is 
used. 
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DESCRIPTION 

LIB$GET_VM satisfies an allocation request by reusing free memory in the 
zone, or by obtaining additional memory from the processwide page pool 
managed by LIB$GET_VM_PAGE. 

LIB$GET_VM rounds up the value of num-bytes to a multiple of the 
block-size specified for the zone. The first byte allocated is aligned on the 
boundary specified by the alignment value for the zone. 

If you specified allocation filling when you created the zone, LIB$GET_VM 
will fill each byte allocated. Otherwise, LIB$GET_VM does not initialize the 
memory and its contents are unpredictable. 

All memory allocated by LIB$GET_VM has user mode read/write access, 
even if the call to LIB$GET_VM was made from a more privileged access 
mode. 

The space allocated by successive calls to LIB$GET_VM may be 
noncontiguous because another procedure can call LIB$GET_VM between 
your calls. If AST interrupts occur, LIB$GET_VM may allocate space to 
another procedure between execution of any two statements in your program. 
Even if successive calls to LIB$GET_VM return two contiguous blocks, you 
must not combine them into one large block that is freed by a single call to 
LIB$FREE_VM. 

LIB$GET_VM is fully reentrant, so it may be called by procedures executing 
at AST level or in an Ada multitasking environment. 

Your program must retain the address of the allocated area. This allows you 
to access or deallocate the space later. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_INSVIRMEM Insufficient virtual memory. The request required 

more dynamic memory than was available from the 
operating system. No partial allocation is made in 
this case. 

LIB$_BADBLOSIZ Bad block size. The value of num-bytes was less 

than or equal to zero. 

LIB$_BADBLOADR Invalid zone-id. 

LIB$_PAGLIMEXC Allocation exceeds the zone's page-limit. 
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LIB$GET_VM_PAGE—Get Virtual Memory 



Page 

LIB$GET_VM_PAGE allocates a specified number of contiguous 
pages of memory in the program region and returns the virtual 
address of the first page allocated. 

FORMAT 

LIB$GET_VM_PAGE num-pages , base-adr 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

num-pages 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Number of pages. The num-pages argument is the address of a longword 
integer which specifies the number of contiguous pages to be allocated. The 
value of num-pages must be greater than zero. 

base-adr 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Block address. The base-adr argument is the address of a longword which is 
set to the address of the first byte of the newly allocated block of pages. 

DESCRIPTION 

LIB$GET_VM_PAGE allocates blocks of contiguous (512 byte) pages in the 
program region. LIB$GET_VM_PAGE manages a processwide pool of free 
pages. If there are not enough contiguous free pages to satisfy an allocation 
request, additional pages are created by calling the system service $EXPREG. 
All memory allocated by LIB$GET_VM__PAGE is page aligned; that is, the 
low-order nine bits of the base address are zero. 

All memory allocated by LIB$GET_VM_PAGE has user-mode read/write 
access, even if the call to LIB$GET_VM_PAGE is made from a more 
priveleged access mode. 

The contents of memory allocated by LIB$GET_VM_PAGE are unpredictable. 
Your program must assign values to all locations that it uses. 

LIB$GET_VM__PAGE is designed for request sizes ranging from one page 
to a few hundred pages. For very large request sizes (over 1000 pages in a 
single request), you should call the system service $EXPREG. 
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CONDITION 

VALUES 

RETURNED 


LIB$GET_VM_PAGE is fully reentrant, so it can be called by procedures 
executing at AST level or in an Ada multitasking environment. 


SS$_NORMAL 

LIB$_BADBLOSIZ 

LIB$_INSVIRMEM 


Normal successful completion. 

The value of the argument num_pages is less than 
or equal to 0. 

Insufficient virtual memory. The request required 
more dynamic memory than was available from the 
operating system. No partial allocation is made in 
this case. 
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LIB$ICHAR—Convert First Character of 

String to Integer 

LIB$ICHAR converts the first character of a source string to an 8-bit 
ASCII integer extended to a longword. 

FORMAT 

LIB$ICHAR src-str 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

First character of the source string. This character is returned by LIB$ICHAR 
as an 8-bit ASCII value extended to a longword. If the source string has zero 
length, LIB$ICHAR returns a zero. 

ARGUMENT 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string whose first character is converted to an integer by LIB$ICHAR. 
The scr-str argument is the address of a descriptor pointing to this source 
string. 

DESCRIPTION 

Although FORTRAN users can call LIB$ICHAR, it is more efficient to use the 
FORTRAN intrinsic function ICHAR, which generates equivalent code in line. 

CONDITION 

VALUES 

RETURNED 

None. 

EXAMPLE 


PROGRAM ICHAR(INPUT, OUTPUT); 

{+> 

< This program demonstrates how to call LIB$ICHAR 
{ to convert the first character of string to an 
{ integer value. 

<-y 

FUNCTION LIB$ICHAR(SRCSTR : VARYING [A] OF CHAR) : INTEGER; 
EXTERN; 

{+> 

{ Declare the variables to be used. 

{-> 


RTL-171 

















Run-Time Library Routines 

LIB$ICHAR 


VAR 

CHARSTR : VARYING [256] OF CHAR; 

RET.STATUS : INTEGER; 

{+> 

{ Begin the main program. Read the character string, 
{ call LIBN$ICHAR, and print the result. 

{-> 

BEGIN 

WRITELNOEnter string: '); 

READLN(CHARSTR); 

RET.STATUS := LIB$ICHAR(CHARSTR); 

WRITELN(RET_STATUS); 

END. 


The output generated by this PASCAL program is as follows: 

$ RUN I CHAR 
Enter string: 

Pencil sharpener 
80 

$ RUN ICHAR 
Enter string: 
pencil sharpener 
112 

Notice the difference in the output between upper- and lowercase characters. 
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LIB$IIMDEX—Index to Relative Position of 

Substring 

LIB$INDEX returns an index, which is the relative position of the first 
occurrence of a substring in the source string. 

FORMAT 

LIB$INDEX src-str ,sub-str 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The relative position of the first character of the substring if found, or zero if 
not found. 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be searched by LIB$INDEX. The src-str argument is the 
address of a descriptor pointing to this source string. 

sub-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Substring to be found. The sub-str argument is the address of a descriptor 
pointing to this substring. 

DESCRIPTION 

The relative character positions returned by LIB$INDEX are numbered 1, 2, 
n. Thus, zero means that the substring was not found. 

If the substring has a zero length, LIB$INDEX returns the value 1, indicating 
success, no matter how long the source string is. If the source string has 
a zero length and the substring has a nonzero length, zero is returned, 
indicating that the substring was not found. 

FORTRAN users may use the built-in INDEX function rather than calling 
LIB$INDEX directly. 


RTL-173 










Run-Time Library Routines 

LIB$INDEX 


CONDITION 

VALUES 

RETURNED 


None. 
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LIB$IIMIT_TIMER—Initialize Times and 



Counts 

LIB$INIT_TIMER stores the current values of specified times and 
counts for use by LIB$SHOW_TIMER or LIB$STAT_TIMER. 

FORMAT 

LIB$INIT_TIMER [handle-adr] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

handle-adr 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Pointer to a control block where the values of times and counts will be stored. 
The handle-adr argument contains the address of an unsigned longword that 
is this pointer. When you call LIB$INIT_TIMER, you must use the optional 
handle-adr argument only if you want to maintain several sets of statistics 
simultaneously. 

• If handle-adr is omitted, the control block is allocated in static storage. 
This method is not AST reentrant. 

• If handle-adr is zero, a control block is allocated in dynamic heap storage. 
The times and counts will be stored in that block and the address of the 
block returned in handle-adr. This method is fully reentrant and modular. 

• If handle-adr is nonzero, it is considered to be the address of a control 
block previously allocated by a call to LIB$INIT_TIMER. If so, the control 
block is reused, and fresh times and counts are stored in it. 

When LIB$INIT_TIMER returns, the block of storage referred to by handle- 
adr will contain the times and counts. 

DESCRIPTION 

LIB$INIT_TIMER stores the current values of specified times and counts 
in one of three places, depending on the value of the optional handle-adr 
argument. 

You need to call LIB$FREE_TIMER only if you have specified handle-adr in 
LIB$INIT_TIMER and you wish to deallocate all heap storage resources. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_INVARG 

LIB$_INSVIRMEM 


Routine successfully completed. 

Invalid argument; handle-adr is nonzero and the 
block to which it refers was not initialized on a 
previous call to LIB$INIT_TIMER. 

Handle-adr is zero, and there is insufficient virtual 
memory to allocate a storage block. 
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LIB$INSERT_TREE—Insert Entry in a 



Balanced Binary Tree 

LIB$INSERT_TREE inserts a node in a balanced binary tree. 

FORMAT 

LIB$INSERT_TREE treehead,sym-str 

,ctrl-flg ,compare-rtn ,alloc-rtn 
, newnode [, user-da ta] 

RETURNS 

VMS Usage: cond_value 
type: longword (signed) 

access: write only 

mechanism: by value 

ARGUMENTS 

treehead 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Tree head for the binary tree. The treehead argument is the address of a 
longword that is this tree head. 

sym-str 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Key to be inserted. The sym-str argument is the address of a descriptor 
pointing to the symbol key. 

Ctrl- fig 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Control flags. The ctrl-flg argument is the address of the control flags. 
Currently only bit zero is used. 

Bit Description 

0 If clear, the address of the existing duplicate entry is returned. If set, 

duplicate entries are inserted. 
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compare-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied compare routine that LIB$INSERT_TREE calls to compare 
a symbol with a node. The compare-rtn argument is the address of the 
entry mask to the compare routine. The compare-rtn argument is required; 
LIB$INSERT_TREE always calls the compare routine. The value returned by 
the compare routine indicates the relationship between the symbol key and 
the node. 

For more information on the compare routine, see "Call Format for a Compare 
Routine" in the Description section below. 

alloc-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied allocate routine that LIB$INSERT_TREE calls to allocate virtual 
memory for a node. The alloc-rtn argument is the address of the entry mask 
to the allocate routine. The alloc-rtn argument is required; LIB$INSERT_ 
TREE always calls the allocate routine. 

For more information on the allocate routine, see "Call Format for an Allocate 
Routine" in the Description section below. 

newnode 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Location where the new key is inserted. The newnode argument is the 
address of an unsigned longword that is this new node location. 


user-data 

VMS Usage: user_arg 
type: unspecified 

access: unspecified 

mechanism: unspecified 

User data that LIB$INSERT_TREE passes to the compare and allocate 
routines. User-data is an optional argument. 


DESCRIPTION This Description section contains three parts. 

• Guidelines for using LIB$INSERT_TREE 

• Call format for a compare routine 

• Call format for an allocate routine 
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Guidelines for Using LIB$INSERT_TREE 

LIB$INSERT_TREE inserts a node in a balanced binary tree. You supply two 
routines: compare and allocate. The compare routine compares the symbol 
key to the node, and the allocate routine allocates virtual memory for the 
node to be inserted. LIB$INSERT_TREE first calls the compare routine to find 
the location at which the new node is inserted. Then LIB$INSERT_TREE calls 
the allocate routine to allocate memory for the new node. Most programmers 
insert data in the new node by initializing it within the allocate routine as 
soon as memory has been allocated. 

You may pass the data to be inserted into the tree using either the sym-str 
argument alone or both the sym-str and user-data arguments. The sym-str 
argument is required. It may contain all of the data, just the name of the 
node, or the address of the data. If you decide to use sym-str to pass just the 
name of the node, you must use the user-arg argument to pass the rest of the 
data to be inserted in the new node. 

Call Format for a Compare Routine 

The call format of a compare routine is as follows: 

comp&re-rtn sym-str .treehead [.user-data] 

LIB$INSERT_TREE passes both the sym-str and treehead arguments to the 
compare routine, using the same passing mechanism that was used to pass 
them to LIB$INSERT_TREE. The user-data argument is passed in the same 
way, but its use is optional. 

The compare-rtn argument in the call to LIB$INSERT_TREE specifies the 
compare routine. This argument is required. LIB$INSERT_TREE always calls 
the compare routine. 

The value returned by the compare routine is the result of comparing the 
symbol key with the current node. Listed below are the possible values 
returned by the compare routine. 


Value Description 

Negative sym-str is less than the current node 

Zero sym-str is equal to the current node 

Positive sym-str is greater than the current node 


This is an example of a user-supplied compare routine written in BASIC. 

FUNCTION LONG Compare_node ( & 

STRING Key.string, k 

Node_type Node. k 

LONG Dummy) 

! + 

! This function compares the string described by Key.string with 
! the string contained in the data node Node, and returns 0 

! if the strings are equal, -1 if Key.string is < Node, and 

! 1 if Key.string > Node. 

OPTION TYPE = EXPLICIT 

RECORD Node.type 

BYTE Header (9) 

BYTE Length 

STRING Text = 80 

END RECORD Node.type 

DECLARE STRING Node.string 


! Header 
! Length 
! String 
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! Return the result of the comparison. 

i - 


Node.string = SEG$ (Node::Text, i. Node::Length) 


SELECT Key.string 
CASE < Node.string 

Compare.node = -17, 
CASE > Node_string 

Compare.node = 17, 
CASE ELSE 

Compare.node = 07. 
END SELECT 

END FUNCTION 


Call Format for an Allocate Routine 

LIB$INSERT_TREE calls the allocate routine to allocate virtual memory for a 
node. The allocate routine then stores the value of user-data in the field of 
the allocated node. 

The format of the call is as follows: 

*lloc-rtn sym-str .newnode [.user-data] 

LIB$INSERT_TREE passes the sym-str, newnode, and user-data arguments 
to your allocate routine, using the same passing mechanisms that were used 
to pass them to LIB$INSERT_TREE. Use of user data is optional. 

A node header appears at the beginning of each node. The following figure 
illustrates the structure of a node header. 



Therefore, any node you declare that LIB$INSERT_TREE manipulates must 
contain 10 bytes of reserved data at the beginning for the node header. 

How a node is structured depends on how you allocate your user data. You 
can allocate data in one of two ways: 

1 Your data immediately follows the node header. In this case your 
allocation routine must allocate a block equal in size to the sum of your 
data plus 10 bytes for the node header. 
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(4 bytes) 
(4 bytes) 
(2 bytes) 
(variable) 


ZK-1927-84 

2 The node contains the 10 bytes of header information and a longword 
pointer to the user data. 



(4 bytes) 
(4 bytes) 
(4 bytes) 
(2 bytes) 


ZK-1928-84 

The alloc-rtn argument in the call to LIB$INSERT_TREE specifies the allocate 
routine. This argument is required. LIB$INSERT_TREE always calls the 
allocate routine. 

This is an example of a user-supplied allocate routine written in BASIC. 


FUNCTION LONG Alloc.node ( 


& 


STRING Key.string, 

& 


LONG 

Ret.addr, 

A 


LONG 

Dummy) 


j 

Allocate virtual memory for a 

new node. KEY.STRING 


; 

is a descriptor of the string 

to enter into the newly 


j 

i 

allocated node. RET.ADDR will 
of the allocated memory. 

contain the address 



OPTION TYPE = EXPLICIT 
DECLARE LONG Status.code 
EXTERNAL LONG FUNCTION LIB$GET_VM 
EXTERNAL SUB LIB$M0VC3 

• + 

! Allocate node: 10 for header, 1 for length plus length of string 

j - 

Status_code = LIB$GET_VM (10% + LEN (Key.string) + 1%, Ret_addr) 
CALL LIB$ST0P (Status.code) IF (Status.code AND 1%) <> 1% 

! + 

! Store key string length in byte 11 of node. Note that LIB$M0VC3 
! accepts its arguments by reference. 

i - 

CALL LIB$M0VC3 (1%. LEN (Key.string), (Ret.addr + 10%) BY VALUE) 
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! + 

! Store key string in bytes 12:n of node. 

CALL LIB$M0VC3 (LEN (Key.string), Key.string BY REF, A 
(Ret.addr + 11%) BY VALUE) 

Alloc_node = 1% 

END FUNCTION 


CONDITION 

VALUES 

RETURNED 


LIB$_NORMAL 

LIB$_KEYALRINS 

LIB$_INSVIRMEM 


Procedure successfully completed. 

Procedure successfully completed, but a key was 
found in the tree. A new key was not inserted. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program's virtual memory 
requirements have exceeded either your process 
quota (PGFLQUOTA) or the system parameter 
VIRTUALPAGCNT. 



EXAMPLE 


1 %TITLE 1 LIB$ Tree Example In BASIC V2' 

%SBTTL 'Main Program' 

»♦ 

! This program will ask the user to enter a series of strings, 

! one per line. The user will them be permitted to query the 

! program to find strings that were previously entered. At the 

! end, the entire tree will be displayed, along with the sequence 
! number that indicates the order in which the element was entered. 

; 

! This program should serve as an example of the use of LIB$INSERT_TREE, 
! LIB$LOOKUP_TREE and LIB$TRAVERSE_TREE. 


OPTION TYPE = EXPLICIT 
DECLARE INTEGER CONSTANT True = -1 
COMMON STRING Text.line = 80 
DECLARE LONG 

Tree_head 
,New_node 
,Status_code 
,Counter 

RECORD Tree.element 
LONG Seq.num 

LONG Text_len 

STRING Text = 80 
END RECORD Tree_element 


Everything must be declared 
Useful named constant 
Allocate static line buffer 


Some variables A 

Head for the tree A 

New node after insert A 

Return status code A 

Sequence number 


Define the structure of our 
record. This record could 
contain many useful data items 


DECLARE Tree.element Rec 


! Declare an instance of the record 


EXTERNAL LONG FUNCTION LIB$INSERT_TREE 
EXTERNAL SUB LIB$TRAVERSE_TREE 
EXTERNAL LONG FUNCTION LIB$L00KUP_TREE 
EXTERNAL SUB LIB$ST0P 
EXTERNAL LONG 

Compare_node_2 
,Compare_node_3 
,Alloc_node 
,Print.node 

EXTERNAL LONG CONSTANT LIB$_KEYN0TF0U 


Function to insert node 
Routine to walk tree 
Routine to find a node 
Routine to signal fatal error 

Routine entry points A 

Compare entry (2 arg) A 

Compare entry (3 arg) A 

Allocation entry A 

Print entry for walk 

Key not found 


+ 

Initialize the tree to null and open the terminal for I/O. 


# 

m 
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Tree.head = 0*/. 

OPEN 'SYSIINPUT' AS FILE #1 


10 


PRINT 'Enter one word per line, ~Z to begin searching the tree' 

ON ERROR GOTO Input_E0F ! Establish error handler 

! + 

! Loop, reading lines of text until the end of the file. 



Counter * 0 
WHILE True 

LINPUT #1, ’> '; Text.line 

Counter = Counter + 1 

Rec::Seq_Num = Counter 

Rec::Text_len = LEN(TRM$(Text_line)) 

Rec::Text = TRM$(Text_line) 

Status_code = LIB$INSERT_TREE ( ! Insert entry into the tree k 

Tree_head, Rec, 1%, k 

Compare_node_3, Alloc_node, New_node) 

CALL LIBISTOP (Status.code BY VALUE) IF (Status.code AND 1%) <> 1% 

NEXT 
! ♦ 

! End of file encountered. Begin searching the tree, 
i - 

PRINT 

PRINT "You will now be prompted for words to find. Enter one per line." 

Rec::Seq.num = -1% 

WHILE True 
PRINT 

LINPUT #1%, 'Word to find? '; Text.line 
Rec::Text_len = LEN(TRM$(Text.line)) 

Rec:: Text = TRM$ (Text ..line) 

Status.code = LIB$L00KUP_TREE (Tree_head, Rec, Compare_Node_2, New.node) 

IF Status.code = LIB$_KEYN0TF0U 

THEN 

PRINT "The word you entered does not appear in the tree" 

ELSE 

CALL Display.Node (New.node BY VALUE) 

END IF 

NEXT 



!♦ 

! The user has finished searching the tree for specific items. It 
! is now time to traverse the entire tree. 

; - 

PRINT 

PRINT "The following is a dump of the tree. Notice that the words" 
PRINT "are in alphabetical order" 

CALL LIB$TRAVERSE_TREE (Tree.head, Print .node, 0*/. BY VALUE) 


GOTO End_of.program 


Input_E0F: 

! + 

! This is the handler for an exception from INPUT. 



IF ERR = 11 
THEN 

SELECT ERL 
CASE 10 

RESUME 20 
CASE 20 

RESUME 30 
CASE ELSE 

ON ERROR GO BACK 
END SELECT 

ELSE 

ON ERROR GO BACK 
END IF 


! End of file 

! No more input, begin searching tree 

! No more items to search for, traverse 
! tree 

! Resignal the error 
! Resignal the error 


End_of.program: 
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! + 

! This is the end of the program. 

j - 

END 

%TITLE 'LIB$ Tree Example in BASIC V2' 

y,SBTTL 'Function to print a node during tree traversal' 
100 FUNCTION LONG Print.node (Node.type Node, LONG Dummy) 

! ♦ 

! Print the string contained in the current node. 


OPTION TYPE = EXPLICIT 


RECORD Node.type 

BYTE Header (9) 

LONG Seq.Num 

LONG Length 

STRING Text = 80 

END RECORD Node.type 

PRINT Node::Seq.Num, SEG$ 

Print.node = 1% 

END FUNCTION 


! Header 

! Sequence number 
! Length 
! String 

(Node : : Text, 1'/,, Node : : length) 


%TITLE *LIB$ Tree Example in BASIC V2' 
%SBTTL 'Function to allocate VM for a node' 
200 FUNCTION LONG Alloc.node ( 


Tree.element 

LONG 

LONG 


Rec, 

Ret.addr, 
Dummy) 


Allocate virtual memory for a new node. Rec is the 
data record to be entered into the newly 
allocated node. RET.ADDR will contain the address 
of the allocated memory. 


& 

k 

k 


OPTION TYPE = EXPLICIT 

RECORD Tree.element ! 

LONG Seq.num ! 

LONG Text.len ! 

STRING Text = 80 

END RECORD Tree.element 

DECLARE LONG Status.code, Data.len 
EXTERNAL LONG FUNCTION LIB$GET_VM 
EXTERNAL SUB LIB$M0VC3 

! + 

! Calculate the length of our data. 

I - 

Data.len = 8% + Rec::Text.len 

! + 

! Allocate node: 10 for header, plus the length of our data. 

i - 

Status.code = LIB$GET_VM (10% ♦ Data.len, Ret.addr) 

CALL LIBISTOP (Status.code) IF (Status.code AND 1%) <> 1% 

! + 

! Store the data in the newly allocated virtual memory. Note 
! that we pass the first field by reference, which is the same 
! as passing the address of the entire record. We add 10 to the 
! address of the VM and pass the result by value so LIB$M0VC3 
! receives the address that marks the beginning of our data in 
! the node. 

I - 

CALL LIB$M0VC3 (Data.Len, Rec: : Seq.Num, (Ret.addr + 10'/.) BY VALUE) 
Alloc.node = 1% 

END FUNCTION 

%TITLE 'LIB$ Tree Example in BASIC V2' 
y,SBTTL 'Function to compare two nodes' 


Define the structure of our 
record. This record could 
contain many useful data items 
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300 FUNCTION LONG Compare_node_3 ( 


Tree_element 

Node.type 


LONG 


OPTION TYPE = EXPLICIT 


Rec, 
Node, 
Dummy) 


& 

& 

& 


RECORD Tree_element 
LONG Seq.num 

LONG Text.len 
STRING Text = 80 
END RECORD Tree.element 

RECORD Node.type 

BYTE Header (9) 
LONG Seq.Num 

LONG Length 

STRING Text = 80 
END RECORD Node.type 


! Define the structure of our 
! record. This record could 
! contain many useful data items 


! Header 

! Sequence number 
! Length 
! String 


EXTERNAL LONG FUNCTION Compare_node_2 


! + 

! Call the 2 argument version of the compare routine. 

i - 


Compare_node_3 = Compare_node.2 ( Rec, Node ) 

END FUNCTION 

310 FUNCTION LONG Compare_node_2 ( & 

Tree.element Rec, & 

Node.type Node) 

! + 

! This function compares the string described by Key.string with 
! the string contained in the data node Node, and returns 0 

! if the strings are equal, -1 if Key.string is < Node, and 

! 1 if Key.string > Node. 


OPTION TYPE = EXPLICIT 

RECORD Tree.element 

LONG Seq.num 

LONG Text.len 

STRING Text = 80 

END RECORD Tree.element 

RECORD Node.type 

BYTE Header (9) 

LONG Seq.Num 

LONG Length 

STRING Text = 80 

END RECORD Node.type 


! Return the result of the comparison. 


Node.string = SEG$ 

(Node::Text 

Key.string = SEG$ i 

(Rec::Text, 

SELECT Key.string 


CASE < Node.string 


Compare_node_2 

= -iy. 

CASE > Node.string 


Compare_node_2 

= 1% 

CASE ELSE 


Compare_node_2 

= oy. 


END SELECT 
END FUNCTION 

y,TITLE 'LIB$ Tree Example in BASIC V2' 
y.SBTTL 'Function to display node data' 
400 SUB Display.node ( 

Node.type Node ) 


! Define the structure of our 
! record. This record could 
! contain many useful data items 


! Header 

! Sequence number 
! Length 
! String 


, i. Node::Length) 
1, Rec::Text.len) 


DECLARE STRING Node.string, Key.string 


This routines prints the data into the node of the tree 
once LIB$L00KUP_TREE has been called to find the node. 
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RECORD Node.type 


BYTE 

Header (9) 

! Header 

LONG 

Seq_Num 

! Sequence number 

LONG 

Length 

! Length 

STRING 

Text = 80 

! String 

END RECORD 

Node_type 



DECLARE STRING Node.string 

Node.string = SEG$ (Node::Text, 1, Node::Length) 

PRINT "The sequence number for ";';Node_string;'"';" is ";Node::Seq.num 
END SUB 


This BASIC example illustrates the use of LIB$INSERT__TREE, 
LIB$LOOKUP—TREE, and LIB$TRAVERSE_TREE. 

The output generated by this program is as follows: 

$ run tree 

Enter one word per line, ~Z to begin searching the tree 

> apple 

> orange 

> peach 

> pear 

> grapefruit 

> lemon 

> <CTRL/Z> 

You will now be prompted for words to find. Enter one per line. 
Word to find? lime 

The word you entered does not appear in the tree 
Word to find? orange 

The sequence number for "orange" is 2 
Word to find? <CTRL/Z> 

The following is a dump of the tree. Notice that the words 
are in alphabetical order 

1 apple 

5 grapefruit 

6 lemon 

2 orange 

3 peach 

4 pear 

$ 
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LIB$INSQHI—Insert Entry at Head of 



Queue 

LIB$INSQHI inserts a queue entry at the head of the specified 
self-relative interlocked queue. LIB$INSQHI makes the VAX/VMS 
INSQHI instruction available as a callable procedure. 

FORMAT 

LIB$INSQHI entry,header[,retry-cnt] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

entry 

VMS Usage: quadword—signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference, array reference 

Entry to be inserted by LIB$INSQHI. The entry argument contains the 
address of this signed quadword-aligned array that must be at least eight 
bytes long. Bytes following the first eight bytes can be used for any purpose 
by the calling program. 

header 

VMS Usage: quadword_signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference 

Queue header specifying the queue into which entry is to be inserted. The 
header argument contains the address of this signed aligned quadword 
integer. Header must be initialized to zero before first use of the queue; zero 
means an empty queue. 

retry-cnt 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The number of times the insertion is to be retried in case of secondary- 
interlock failure of the queue instruction in a processor-shared memory 
application. The retry-cnt argument is the address of an unsigned longword 
that contains the retry count value. A value of 1 causes no retries. The 
default value is 10. 
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DESCRIPTION The queue into which LIB$INSQHI inserts an entry can be in process-private, 

processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library procedure specifies a 
queue entry by its address. Two longwords, a forward link and a backward 
link, define the location of the entry in relation to the preceding and 
succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry's predecessor and successor. The VAX/VMS instructions INSQHI, 
INSQTI, REMQHI, and REMQTI allow you to insert and remove an entry 
at the head or tail of a self-relative queue. Each queue instruction has a 
corresponding Run-Time Library procedure. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the 
current program is doing so. Since the operation requires changing two 
pointers at the same time, a high-level language cannot perform this 
operation without calling the Run-Time Library queue access procedures. 

When you use these procedures, cooperating processes can communicate 
without further synchronization and without danger of being interrupted, 
either on a single processor or in a multiprocessor environment. The queue 
access procedures are also useful in an AST environment; they allow you 
to add or remove an entry from a queue without being interrupted by an 
asynchronous system trap. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_ONEENTQUE 

LIB$_SECINTFAI 


Procedure successfully completed. The entry was 
added to the front of the queue, and the resulting 
queue contains more than one entry. 

Procedure successfully completed. The entry was 
added to the front of the queue, and the resulting 
queue contains one entry. 

A secondary interlock failure occurred; the insertion 
was attempted the number of times specified by 
retry-cnt. This is a severe error. The queue is not 
modified. This condition can occur only when the 
queue is in memory being shared between two or 
more processors. 


EXAMPLES 

Q INTEGER*4 FUNCTION INSERT.Q (QENTRY) 
COMMON/QUEUES/QHEADER 
INTEGERS QENTRY(10) , QHEADER(2) 
INSERT.Q = LIBIINSQHI (QENTRY. QHEADER) 
RETURN 
END 


This is a FORTRAN application using processor-shared memory. 
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Q 


COM (QUEUES) QENTRY*/,(9) , QHEADER'/,(1) 

EXTERNAL INTEGER FUNCTION LIB$INSQHI 

IF LIB$INSQHI (QENTRY%() BY REF, QHEADER*/.() BY REF) AND 1% 


THEN GOTO 1000 


1000 REM INSERTED OK 


In BASIC and FORTRAN, queues can be quadword aligned in a named 
COMMON block by using a linker option file to specify PSECT alignment. 
The Run-Time Library procedure LIB$GET_VM returns memory that is 
quadword aligned. Therefore, you should use LIB$GET_VM to allocate the 
virtual memory for a queue. For instance, to create a COMMON block called 
QUEUES, use the LINK command with the FILE/OPTIONS qualifier, where 
FILE.OPT is a linker option file containing the line: 

PSECT = QUEUES, QUAD 
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LIB$INSQTI—Insert Entry at Tail of Queue 



LIB$INSQTI inserts a queue entry at the tail of the specified self¬ 
relative interlocked queue. LIB$INSQTI makes the VAX INSQTI 
instruction available as a callable procedure. 

FORMAT 

LiB$lNSQTI entry,header[, retry-cnt] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

entry 

VMS Usage: quadword—signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference, array reference 

Entry to be inserted at the tail of the queue by LIB$INSQTI. The entry 
argument contains the address of this signed quadword-aligned array that 
must be at least eight bytes long. Bytes following the first eight bytes can be 
used for any purpose by the calling program. 

header 

VMS Usage: quadword—signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference 

Queue header specifying the queue into which the queue entry is to be 
inserted. The header argument contains the address of this signed aligned 
quadword integer. Header must be initialized to zero before first use of the 
queue; zero means an empty queue. 

retry-cnt 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The number of times the insertion is to be retried in case of secondary- 
interlock failure of the queue instruction in a processor-shared memory 
application. The retry-cnt argument is the address of a longword which 
contains the retry count value. The default value is 10. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


The queue into which LIB$INSQTI inserts an entry can be in process-private, 
processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library procedure specifies a 
queue entry by its address. Two longwords, a forward link and a backward 
link, define the location of the entry in relation to the preceding and 
succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry's predecessor and successor. The VAX instructions INSQHI, INSQTI, 
REMQHI, and REMQTI allow you to insert and remove an entry at the head 
or tail of a self-relative queue. Each queue instruction has a corresponding 
Run-Time Library procedure. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the 
current program is doing so. Since the operation requires changing two 
pointers at the same time, a high-level language cannot perform this 
operation without calling the Run-Time Library queue access procedures. 

When you use these procedures, cooperating processes can communicate 
without further synchronization and without danger of being interrupted, 
either on a single processor or in a multiprocessor environment. The queue 
access procedures are also useful in an AST environment; they allow you 
to add or remove an entry from a queue without being interrupted by an 
asynchronous system trap. 


SSS—NORMAL Procedure successfully completed. The entry was 

added to the tail of the queue: the resulting queue 
contains more than one entry. 

LIB$_ONEENTQUE Procedure successfully completed. The entry was 

added to the tail of the queue: the resulting queue 
contains one entry. 

LIB$_SECINTFAI A secondary interlock failure occurred; the insertion 

was attempted the number of times specified by 
retry-cnt. This is a severe error. The queue is not 
modified. This condition can occur only when the 
queue is in memory being shared between two or 
more processors. 
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LIB$INSV- 

—Insert a Variable Bit Field 

LIB$INSV replaces the variable bit field specified by the base, 
position, and size arguments with bits 0 through (size - 1 )) of the 
source field. If the size of the bit field is zero, nothing is inserted. 
LIB$INSV makes the VAX INSV instruction available as a callable 
procedure. 

FORMAT 

LIB$INSV src ,pos ,size ,base 

RETURNS 

None. 

ARGUMENTS 

src 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Source field to be inserted by LIB$INSV. The src argument is the address of a 
signed longword integer that contains this source field. 

pos 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Bit position relative to the base address where insertion of src is to begin. 

The pos argument is the address of a longword integer that contains this 
relative bit position. 

size 

VMS Usage: byte_unsigned 
type. byte (unsigned) 

access: read only 

mechanism: by reference 

Size of the bit field to be inserted by LIB$INSV. The size argument is the 
address of an unsigned byte which contains the size of this bit field. The 
maximum size is 32 bits. 

base 

VMS Usage: address 
type: aligned bit string 

access: write only 

mechanism: by reference 

Field into which LIB$INSV writes the source field. The base argument 
contains the base address of this aligned bit string. 
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CONDITION SS$_ROPRAND A reserved operand fault is signaled if a size greater 

than 32 is specified. 

SIGNALED 


EXAMPLES 

D INTEGER*4 COND.VALUE 

CALL LIB$INSV (4, 0, 3. COND.VALUE) 

This example shows how to set bits 0 through 2 of longword COND_VALUE 
to the value 4 in FORTRAN. 

B DECLARE INTEGER COND.VALUE 

CALL LIBIINSV (4%, 0*/., 37., COND.VALUE) 

This example uses BASIC to set bits 0 through 2 of longword COND_VALUE 
to the value 4. 
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LIB$INT_OVER—Integer Overflow 



Detection 

LIB$INT_OVER enables or disables integer overflow detection for 
the calling procedure activation. The previous integer overflow 
enable setting is returned. 

FORMAT 

LIB$INT_OVER new-setting 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Old integer overflow enable setting (the previous contents of SF$W__ 
PSW[PSW$V_IV] in the caller's frame). 

ARGUMENT 

new-setting 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

New integer overflow enable setting. The new-setting argument is the 
address of an unsigned byte which contains the new integer overflow enable 
setting. Bit 0 set to 1 means enable, bit 0 set to 0 means disable. 


DESCRIPTION The caller's stack frame will be modified by this procedure. 



LIB$INT_OVER affects only the current procedure activation and does not 
affect any of its callers or any procedures that it may call. However, the 
setting remains in effect for any procedures which are subsequently entered 
through a JSB entry point. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


INTOVF: PROCEDURE OPTIONS (MAIN); 

DECLARE LIB$INT_OVER ENTRY (FIXED BINARY (7)) /* Address of byte for 

/* enable/disable 
/* setting */ 

RETURNS (FIXED BINARY (31)); /* Old setting */ 

DECLARE DISABLE FIXED BINARY (7) INITIAL (0) STATIC READONLY; 

DECLARE (A,B) FIXED BINARY (7); 

ON FIXEDOVERFLOW PUT SKIP LIST ('Overflow'); 

A = 127; 

B = A + 2; 

PUT LIST ('In MAIN'); 

BEGIN; 

DECLARE RESULT FIXED BINARY (31); 

/* Disable recognition of integer overflow in this block */ 

RESULT = LIBIINT.OVER (DISABLE); 

B = A + 2; 

PUT SKIP LIST ('In BEGIN block'); 

CALL Q; 

Q: PROCEDURE; 

B = A + 2; 

PUT LIST ('In Q'); 

END Q; 

END /* Begin */; 

END INTOVF; 


This PL/I procedure shows how to use LIB$INT_OVER to enable or disable 
the detection of integer overflow. Note that in PL/I integer overflow 
is always enabled unless explicitly overridden by a call to this routine. 
However, disabling integer overflow is only effective for the block which calls 
this routine; descendent blocks are unaffected. The output generated by this 
PL/I program is as follows: 

In MAIN 

In BEGIN block 

Overflow In Q 
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LIB$LEN— 

-Length of String Returned as 
Longword Value 

LIB$LEN returns the length of a string. 

FORMAT 

LIB$LEN src-str 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Length of the source string, extracted and zero-extended to 32 bits. 

ARGUMENT 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string whose length is returned by LIB$LEN. The src-str argument 
contains the address of a descriptor pointing to this source string. 

DESCRIPTION 

The maximum length of a VAX/VMS string is 65,535 characters. 

The BASIC and FORTRAN intrinsic function LEN generates equivalent in-line 
code at run time. Therefore, it is more efficient for BASIC and FORTRAN 
users to use the intrinsic function LEN than to call LIB$LEN. 

If you need both the length of the string and the address of its first byte, you 
should use LIB$ANALYZE__SDESC instead. 

CONDITION 

VALUES 

RETURNED 

None. 
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LIB$LOCC—Locate a Character 

LIB$LOCC locates a character in a string by comparing successive 



bytes in the string with the character specified. The search 
continues until the character is found or the string has no more 
characters. LIB$LOCC makes the VAX LOCC instruction available as 
a callable procedure. 

FORMAT 

LIB$LOCC char-str,src-str 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The relative position from the start of src-str to the first equal character or 
zero if no match is found. 

ARGUMENTS 

char-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String whose initial character is used by LIB$LOCC in the search. The 
char-str argument contains the address of a descriptor pointing to this string. 
Only the first character of char-str is used, and its length is not checked. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String to be searched by LIB$LOCC. The src-str argument is the address of a 
descriptor pointing to this character string. 

DESCRIPTION 

LIB$LOCC returns the position of the first equal character relative to the start 
of the source string as an index. An index is the relative position of the first 
occurrence of a substring in the source string. If no character matches, or if 
the string has a length of zero, then a zero is returned, indicating that the 
character was not found. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLES 


IDENTIFICATION DIVISION. 
PROGRAM-ID. LIBLOC. 

ENVIRONMENT DIVISION. 

DATA DIVISION. 
WORKING-STORAGE SECTION. 


01 

SEARCH-STRING 

PIC X(26) 

VALUE -ABCDEFGHIJKLMNOPQRSTUVWXYZ- 

01 

SEARCH-CHAR 

PIC X. 

01 

IND-POS 

PIC 9(9) USAGE IS COMP. 

01 

DISP-IND 

PIC 9(9). 


PROCEDURE DIVISION. 


OOl-MAIN. 

MOVE SPACE TO SEARCH-CHAR. 

DISPLAY M ". 

DISPLAY "ENTER SEARCH CHARACTER: " WITH NO ADVANCING. 

ACCEPT SEARCH-CHAR. 

CALL "LIB$LOCC" 

USING BY DESCRIPTOR SEARCH-CHAR, SEARCH-STRING 
GIVING IND-POS. 

IF IND-POS = ZERO 
DISPLAY 

-CHAR ENTERED (" SEARCH-CHAR ") NOT A VALID SEARCH CHAR- 
STOP RUN. 

MOVE IND-POS TO DISP-IND. 

DISPLAY 

-SEARCH CHAR (" SEARCH-CHAR ") WAS FOUND IN POSITION " 
DISP-IND. 

GO TO OOl-MAIN. 


This COBOL program accepts a character as input and returns as output the 
character's position in a search string. The output generated by this COBOL 
program is as follows: 


$ RUN LIBLOC 

ENTER SEARCH CHARACTER: X 

SEARCH CHAR (X) WAS FOUND IN POSITION 000000024 
ENTER SEARCH CHARACTER: Y 

SEARCH CHAR (Y) WAS FOUND IN POSITION 000000025 
ENTER SEARCH CHARACTER: B 

SEARCH CHAR (B) WAS FOUND IN POSITION 000000002 


ENTER SEARCH CHARACTER: b 

CHAR ENTERED (b) NOT A VALID SEARCH CHAR 

$ 


Notice that upper- and lowercase letters are not considered equal. 


E 10 ! + 

! This is an BASIC program demonstrating the 
! use of LIB$LOCC. 

I - 

EXTERNAL INTEGER FUNCTION LIB$LOCC 
1 % - 0 

CHARSTRI * ‘DAY’ 

SRCSTRI = 'ONE DAY AT A TIME* 

17. = LIB$LOCC (CHARSTR$, SRCSTR$) 

PRINT 17. 

90 END 


This BASIC example also illustrates the use of LIB$LOCC. The output 
generated by this BASIC program is "5". 
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LIB$LOOKUP_KEY—Look Up Keyword in 



Table 

LIB$LOOKUP_KEY scans a table of keywords to find one that 
matches the keyword or keyword abbreviation specified by search- 
str. 

FORMAT 

LIB$LOOKUP_KEY search-strkey-table 
[,key-value] 

[, full-str] [, out-len] 

RETURNS 

VMS Usage: cond_value 
type: long word (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

search-str 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

String for which LIB$LOOKUP_JKEY will search in the keyword table. The 
search-str argument is the address of a descriptor pointing to this string. 

key-table 

VMS Usage: longword—unsigned 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Keyword table. The key-table argument contains the address of an array of 
unsigned longwords that is this keyword table. 

key-value 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Value of the keyword found by LIB$LOOKUP_KEY. The key-value 
argument contains the address of an unsigned longword that is this keyword 
value. LIB$LOOKUP—KEY writes the address of this unsigned longword into 
key-value. 
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full-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Full keyword match. The full-str argument contains the address of a 
descriptor pointing to the keyword string. LIB$LOOKUP_KEY writes the 
address of this descriptor into full-str if the full keyword is matched. 


out-len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of characters in the keyword, independent of padding. The out-len 
argument is the address of a signed word integer that contains the number 
of characters in the keyword. LIB$LOOKUP_KEY writes the address of this 
signed word integer into out-len. 


DESCRIPTION LIB$LOOKUP_KEY is intended to help programmers writing utilities that 

have command qualifiers with values. 

LIB$LOOKUP_KEY locates a matching keyword or keyword abbreviation by 
comparing the first n characters of each keyword in the keyword table with 
the supplied string, where n is the length of the supplied string. 

When a keyword match is found, the following information is optionally 
returned to the caller. 

• The longword value associated with the matched keyword 

• The full keyword string (any descriptor type) 

An exact match is found if the length of the keyword found is equal to the 
length of the supplied string. 

If an exact keyword match is found, no further processing is performed, and 
a normal return status is returned to the caller. Otherwise, after a match has 
been found, the rest of the keyword table is scanned. If an additional match 
is found, a "not enough characters" return status is returned to the caller. 

If the keyword table contains a keyword that is an abbreviation of another 
keyword in the table, an exact match can occur for short abbreviations. 

See Figure RTL-5 for the structure of the keyword table, which the calling 
program creates for this procedure. 

Vector-count is the number of longwords that follow, and counted-ASCII- 
string starts with a byte that is the unsigned count of the number of ASCII 
characters that follow. 

Because of the format of the keyword table, this procedure cannot be called 
easily from high-level languages. The examples show how to use a macro, 
$LIB_KEY_TABLE, to construct a keyword table from MACRO or BLISS. A 
separate example shows how a table could be constructed in FORTRAN. 

Use of the $LIB_KEY_TABLE macro results in data that is not position- 
independent code (PIC). If your application requires PIC data, you must fill 
in the address of the keyword strings at execution time. See the FORTRAN 
example for a demonstration of this technique. 
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Figure RTL-5 Keyword Table 


vector 


vector-count 


address of keyword string 


f keyword string 

associated keyword value 


counted-ASCII-string 


ZK-1976-84 


CONDITION SS$_NORMAL 

VALUES 

RETURNED lib$_ambkey 

LIB$_INVARG 

LIB$_INSVIRMEM 

LIB$_STRTRU 

LIB$_UNRKEY 


Procedure successfully completed. A unique 
keyword match was found. 

Multiple keyword match found. Not enough 
characters were specified to allow a unique match. 

Invalid arguments, not enough arguments, and/or 
bad keyword table. 

Insufficient virtual memory to return keyword 
string. This is only possible if full-str is a dynamic 
string. 

String truncated. 

The keyword you specified does not appear in the 
keyword table you specified. 


EXAMPLES 

D KEYTABLE: 

$LIB_KEY_TABLE < - 

<ADD, 1>. - 
<DELETE, 2>, - 
<EXIT, 3» 

This MACRO fragment defines a keyword table named KEYTABLE containing 
the three keywords ADD, DELETE, and EXIT with associated keyword values 
of 1, 2, and 3, respectively. 

The $LIB__KEY_TABLE macro is supplied in the default macro library 
SYS$LIBRARY:STARLET.MLB. Because this library is automatically searched 
by the assembler, you do not have to specify it in the DCL command 
MACRO. 
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LIBRARY 'SYS$LIBRARY:STARLET.L32'; 
OWN 

KEYTABLE: $LIB_KEY_TABLE ( 
(ADD. 1). 

(DELETE. 2). 

(EXIT. 3)); 


This BLISS code fragment specifies that SYS$LIBRARY:STARLET.L32 is to be 
searched to resolve references. It defines a keyword table named KEYTABLE 
containing the three keywords ADD, DELETE, and EXIT with associated 
keyword values of 1, 2, and 3, respectively. 

The $LIB_KEY_TABLE macro is supplied in the BLISS library 
SYS$LIBRARY:STARLET.L32 and in the BLISS require file 
SYS$LIBRARY:STARLET.REQ. BLISS does not automatically search either of 
these files so you must explicitly cause them to be searched by including the 
appropriate LIBRARY or REQUIRE statement in your module. You should 
use the precompiled library because it is more efficient for the compiler. 


PARAMETER ( 

1 MAXKEYSIZE =6, ! Maximum keyword size 

2 NKEYS = 3) ! Number of keywords 


BYTE KEYWORDS (MAXKEYSIZE+1. NKEYS) 
INTEGERS KEYTABLE (0:NKEYS*2) 

DATA KEYWORDS / 

1 3, 'A' . 'D\ *D' . ' ',' ',' ', 

6.'D'.'E'.'L','E','T'.'E'. 

4.'E'.'X'.'I'.'T'.' '.' '/ 

KEYTABLE(0) = NKEYS*2 

KEYTABLE (1) = y.L0C (KEYWORDS (1.1) ) 

KEYTABLE(2) = 1 

KEYTABLE (3) = '/.LOC (KEYWORDS (1,2)) 
KEYTABLE(4) * 2 

KEYTABLE (5) = ‘/.LOC (KEYWORDS (1.3) ) 
KEYTABLE(6) = 3 


! Counted ASCII 'ADD 1 
! Counted ASCII 'DELETE' 

! Counted ASCII 'EXIT' 

! Number of longwords to follow 
! Address of keyword string 
! Keyword value for 'ADD' 

! Address of keyword string 
! Keyword value for 'DELETE' 

! Address of keyword string 
! Keyword value for 'EXIT' 


This FORTRAN code fragment constructs a keyword table named KEYTABLE 
containing the three keywords ADD, DELETE, and EXIT with associated 
keyword values of 1, 2, and 3, respectively. This construction method results 
in position-independent coded data, although the generated code for the 
typical FORTRAN module contains other non-PIC values. 
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LIB$LOOKUP_TREE—Look Up an Entry in 

a Balanced Binary 
Tree 

LIB$LOOKUP_TREE looks up an entry in a balanced binary tree. 


FORMAT 

LI B$ LOOKUP-TREE 

treehead, sym-str, compare-rtn 
,newnode 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

treehead 



VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Tree head for the binary tree. The treehead argument is the address of an 
unsigned longword that is this tree head. 


sym-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Key to be looked up in the binary tree. The sym-str argument is the address 
of a descriptor pointing to the symbol key. 


compare-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied compare routine that LIB$LOOKUP_TREE calls to compare a 
symbol with a node. The compare-rtn argument is the address of the entry 
mask to the compare routine. The value returned by the compare routine 
indicates the relationship between the symbol key and the current node. 

Listed below are the possible values of the compare-rtn argument and their 
meanings. 
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Value Description 

Negative sym-str is less than the current node 

Zero sym-str is equal to the current node 

Positive sym-str is greater than the current node 


For more information on the compare routine, see "Call Format for a Compare 
Routine" in the Description section. 


newnode 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Location where the new symbol was found. The newnode argument is the 
address of an unsigned longword that is the new node location. 


DESCRIPTION 

Call Format for a Compare Routine 

The call format for a compare routine is as follows: 

compare-rtn sym-str .treehead 

LIB$LOOKUP_TREE passes the sym-str and treehead arguments to the 
compare routine using the same passing mechanism that was used to pass 
them to LIB$LOOKUP-TREE. 


CONDITION LIB$_NORMAL 

VALUES LIB$_KEYNOTFOU 

RETURNED 


Success. The key was found. 
Error. The key was not found. 


EXAMPLE 


The BASIC example provided in the description of LIB$INSERT_TREE also 
demonstrates how to use LIB$LOOKUP_TREE. Please refer to that example 
for assistance in using this procedure. 
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LIB$LP_LINES—Lines on Each Printer 



Page 

LIB$LP_LINES computes the default number of lines on a printer 
page. This procedure can be used by native-mode VAX/VMS 
utilities that produce listing files and do pagination. 

FORMAT 

LIB$LP_LINES 

RETURNS 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by value 

The default number of lines on a physical printer page. If the logical name 
translation or conversion to binary fails, a default value of 66 is returned. 

ARGUMENTS 

None. 

DESCRIPTION 

The algorithm used by LIB$LP_LINES is: 

1 Translate the logical name SYS$LP_LINES. 

2 Convert the ASCII value obtained to a binary integer. 

3 Verify that the resulting value is in the range [30:255]. 

4 If any of the prior steps fail, return the default paper size of 66 lines. 

You can use LIB$LP_LINES to monitor the current default length of the line 
printer page. You can also supply your own default length for the current 
process. United States standard paper stock permits 66 lines on each physical 
page. 

If you are writing programs for a utility that formats a listing file to be 
printed on a line printer, you can use LIB$LP_LINES to make your utility 
independent of the default page length. Your program can use LIB$LP_ 
LINES to obtain the current length of the page. It can then calculate the 
number of lines of text on each page by subtracting the lines used for margins 
and headings. 

The following is one suggested format. 

1 Three lines for the top margin 

2 Three lines for the bottom margin 
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3 Three lines for listing heading information, consisting of: 
a Language-processor identification line 
b Source-program identification line 
c One blank line 


CONDITION None. 

VALUES 

RETURNED 


EXAMPLES 

E lplines = LIB$LP_LINES() 

PRINT 10, lplines 

10 Format (' Line printer page = ',15,' lines.') 

end 

This FORTRAN program displays the current default length of the line printer 
page. 

E LINES: PROCEDURE OPTIONS (MAIN); 

DECLARE LIB$LP_LINES EXTERNAL ENTRY 
RETURNS (FIXED BINARY (31)); 

PUT SKIP LIST ('Line printer page * ',LIB$LP_LINES().' lines.'); 

END; 


This PL/I program displays the current default length of the line printer page. 

100 EXTERNAL INTEGER FUNCTION LIB$LP_LINES 

200 DECLARE INTEGER LPLINES 

300 LPLINES = LIB$LP_LINES 

400 PRINT "Line printer page =* "; LPLINES 

32767 END 

This BASIC program displays the current default length of the line printer 
page. 

PROGRAM LINES(OUTPUT); 

FUNCTION LIB$LP_LINES : INTEGER; 

EXTERN; 

BEGIN 

WRITELN('Line printer page = ',LIB$LP_LINES,' lines.'); 

END. 


This PASCAL program displays the current default length of the line printer 
page. 
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IDENTIFICATION DIVISION. 

PROGRAM-ID. PAGELINES. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 LPLINES PIC 9(9) USAGE IS COMP 

VALUE IS 999999999. 

01 SHOWLPLINES PIC 9(9). 

PROCEDURE DIVISION. 

PO. 

CALL "LIB$LP_LINES" 

GIVING LPLINES. 

MOVE LPLINES TO SHOWLPLINES. 

DISPLAY "Line printer page = ", SHOWLPLINES, " lines.". 
STOP RUN. 


This COBOL program displays the current default length of the line printer 
page. 
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LIB$MATCHC—Match Characters, Return 

Relative Position 


LIB$MATCHC searches a source string for a specified substring and 
returns an index, which is the relative position of the first occurrence 
of a substring in the source string. LIB$MATCHC makes the VAX 
MATCHC instruction available as a callable procedures. 

FORMAT 

LIB$MATCHC sub-str,scr-str 

RETURNS 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The relative position of the first character of the substring if found, or zero if 
not found. 

ARGUMENTS 

sub-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Substring to be found. The sub-str argument is the address of a descriptor 
pointing to this substring. 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be searched by LIB$MATCHC. The src-str argument is the 
address of a descriptor pointing to this source string. 

DESCRIPTION 

The relative character positions returned by LIB$MATCHC are numbered 1, 

2, ..., n. Thus, zero means that the substring was not found. 


If the substring has a zero length, LIB$MATCHC returns the value 1, 
indicating success, no matter how long the source string is. If the source 
string has a zero length and the substring has a nonzero length, zero is 
returned, indicating that the substring was not found. 

The order of arguments for LIB$MATCHC parallels the VAX MATCHC 
instruction. 
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CONDITION 

VALUES 

RETURNED 


None. 
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LIB$MATCH_COND—Match Condition 

Values 



LIB$MATCH_COND checks to see if a given condition value 
matches a list of condition values that you supply. 

FORMAT 

LIB$MATCH_COND cond-val , cond-val-i 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 

A zero, if the input condition value did not match any condition value in the 
list, or i-1 , for a match between the first argument and the ith argument. 

ARGUMENTS 

cond-val 

VMS Usage: cond—value 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Condition value to be matched. The cond-val argument is the address of an 
unsigned longword that contains this condition value. 

cond-val-i 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The condition value(s) to be compared to cond-val. The cond-val-i 
argument(s) are the address(es) of the unsigned longword(s) that contain 
these condition value(s). 

DESCRIPTION 

LIB$MATCH__COND checks for a match between the condition value 
addressed by cond-val and the condition values addressed by the subsequent 
arguments. Each argument is the address of a longword containing a 
condition value. 

LIB$MATCH_COND is provided for programmers who want to match a 
list of one or more condition values. It is designed to be used in multi-path 
branch statements available in most higher-level languages. 

LIB$MATCH_COND compares the portion (STS$V_COND_ID) of the 
condition value referenced by the first argument to the same portion of the 
condition value referenced by the second through Nth arguments. If the 
facility-specific bit (STS$V_FAC_SP = bit 15) is clear in cond-val (meaning 
that the condition value is system wide rather than facility specific), the 
facility code field (STS$V_FAC_NO = bits 27:17) is ignored and only the 
STS$V_MSG_ID fields (bits 15:3) are compared. 
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The routine returns a zero if a match is not found, a 1 if the condition 
value matches the first condition value in the list (the second argument), a 
2 if it matches the second condition value (the third argument), and so on. 
LIB$MATCH_COND checks for null argument entries in the argument list. 

When LIB$MATCH_COND is called with only two arguments, the possible 
values for the value returned are true (1) or false (zero). 

Each condition handler must examine the signal argument vector to determine 
which condition is being signaled. If the condition is not one that the handler 
knows about, the handler should resignal. A handler should not assume that 
only one kind of condition can occur in the procedure which established it 
or in any procedures it calls. However, because a condition value may be 
modified by an intervening handler, each handler should only compare that 
part of the condition value that distinguishes it from another. 


CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 


C+ 

C This FORTRAN progrm demonstrates the use of 

C LIBIMATCH.COND. 

C 

C Declare handler routine as external. 

C- 

EXTERNAL HANDLER 

C+ 

C Declare the handler that will be used. 

C- 

TYPE * , 'Establishing handler...' 

CALL LIB$ESTABLISH( HANDLER ) 

OPEN ( UNIT = 1 , NAME = 'MATCH.DAT' , STATUS = 'OLD' ) 

C+ 

C Revert to normal error processing. 

C- 

CALL LIBIREVERT 
CLOSE ( UNIT = 1 ) 

CALL EXIT 
END 
C+ 

C This is the handler routine. 

C- 

INTEGER*4 FUNCTION HANDLER( SIGARGS . MECHARGS ) 

INTEGER+4 MECHARGS(*) , SIGARGS(*) , STATUS 
INCLUDE '($SSDEF)' 

INCLUDE '($F0RDEF)' 

HANDLER = SS$_CONTINUE 

C+ 

C This handler will type out an error message. In this case the 

C message is regarding a file open status. 

C- 


TYPE * , 'Entering handler...' 

STATUS = LIB$MATCH_COND( SIGARGS( 2 ) . FOR$_FILNOTFOU , 
1 FOR$_NO_SUCDEV , FOR$_FILNAMSPE . F0R$_0PEFAI ) 

GOTO ( 100 . 200 , 300 , 400 ) STATUS 
HANDLER = SS$_RESIGNAL 
GOTO 1000 
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100 

TYPE * 
GOTO 

. 'ERROR 
1000 

-- File not found' 

200 

TYPE * 
GOTO 

, 'ERROR 
1000 

No such Device' 

300 

TYPE * 
GOTO 

, 'ERROR 
1000 

File name specification' 

400 

TYPE * 

, 'ERROR 

Open Failure' 

1000 

CALL SYS$UNWIND( 

MECHARGS( 3 ) . ) 


TYPE * 

RETURN 

END 

, 'Returning from handler...' 


This FORTRAN program uses a computed GOTO to alter the program 
execution sequence on a condition value. 

If there is no file called MATCH.DAT, the following output is returned: 

Establishing handler... 

Entering handler... 

ERROR -- File not found 
Returning from handler... 

If the file MATCH.DAT does exist, the output returned is as follows: 

Establishing handler... 
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LIB$MOVC3—Move Characters 



LIB$M0VC3 makes the VAX MOVC3 instruction available as a 
callable procedure. The source item is moved to the destination 
item. Overlap of the source and destination items does not affect 
the result. 

FORMAT 

LIB$MOVC3 length,source ,dest 

RETURNS 

None. 

ARGUMENTS 

length 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Number of bytes to be moved from source to dest by LIB$MOVC3. The 
length argument is the address of an unsigned word which contains this 
number of bytes. The maximum transfer is 65,535 bytes. 

source 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

Item to be moved. The source argument is the address of this item. 

dest 

VMS Usage: address 
type: unspecified 

access: write only 

mechanism: by reference 

Item into which source will be moved. The dest argument is the address of 
this item. 

DESCRIPTION 

LIB$MOVC3 is useful for moving large blocks of data, such as arrays, when 
such an operation would otherwise have to be performed by a programmed 
loop. 

For more information, see the VAX-11 Architecture Reference Manual. See also 
OTS$MOVE3. 

CONDITION 

VALUES 

RETURNED 

None. 
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LIB$MOVC5—Move Characters with Fill 

LIB$M0VC5 makes the VAX M0VC5 instruction available as a 



callable procedure. The source item is moved to the destination 
item. Overlap of the source and destination items does not affect 
the result. 

FORMAT 

LIB$MOVC5 src-len,source ,fill ,dst-len ,dest 

RETURNS 

None. 

ARGUMENTS 

src-len 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Number of bytes in the source item. The src-len argument is the address of 
an unsigned word that contains this number of bytes. The maximum length 
of source is 65,535 bytes. 

source 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

Item to be moved by LIB$MOVC5. The source argument is the address of 
this item. If src-len is zero, indicating that dest is to be entirely filled by the 
fill character, then source is ignored by LIB$MOVC5. 

fill 

VMS Usage: byte_signed 
type: byte integer (signed) 

access: read only 

mechanism: by reference 

Character used to pad source to the length of dest. The fill argument is the 
address of a signed byte integer that contains this fill character. 

dst-len 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Length of dest in bytes. The dst-len argument is the address of an unsigned 
word that contains this number of bytes. The maximum value of dst-len is 
65,535 bytes. 
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dest 

VMS Usage: varying_arg 
type: unspecified 

access: write only 

mechanism: by reference 

Item into which source will be moved. The dest argument is the address of 
this item. 

DESCRIPTION 

If the destination item is shorter than the source item, the highest-addressed 
bytes of the source are not moved. 

For more information, see the VAX Architecture Reference Manual. See also 
OTS$MOVE5. 

CONDITION 

VALUES 

RETURNED 

None. 


April 1986 
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LIB$MOVTC—Move Translated Characters 



LIB$MOVTC moves the source string, character by character, to the 
destination string after translating each character using the specified 
translation table. LIB$MOVTC makes the VAX MOVTC instruction 
available as a callable procedure. 

FORMAT 

LI B$MOVTC src-str, fill-char , trans-tbl,dst-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be translated and moved by LIB$MOVTC. The src-str 
argument is the address of a descriptor pointing to this source string. 

fill-char 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Fill character used to pad src-str to the length of dst-str. The fill-char 
argument is the address of a descriptor pointing to a string. The first character 
of this string is used as the fill character. The length of this string is not 
checked and fill-char is not translated. 

trans-tbl 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Translation table used by LIB$MOVTC. The trans-tbl argument is the address 
of a descriptor pointing to the translation table string. The translation table 
string is assumed to be 256 characters long. 

You can use any one of the translation tables included in the Description 
section that follows, or you can create your own. When using a translation 
table supplied by DIGITAL, the names LIB$AB_xxx_yyy represent the 
addresses of the 256 byte translation tables, and can be accessed as external 
(string) variables. If a particular language cannot generate descriptors for 
external strings, then they must be created manually. The example following 
the Description section illustrates the creation of a string descriptor for a 
translation table using VAX BASIC. 
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dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$MOVTC writes the translated src-str. The 
dst-str argument is the address of a descriptor pointing to this destination 
string. 


DESCRIPTION Each character in the source string is used as an index into the translation 

table. The byte found is then placed into the destination string. The fill 
character is used if the destination string is longer than the source string. 

If the source string is longer than the destination string, the source string 
is truncated. Overlap of the source and destination strings does not affect 
execution. 

The translation tables used by LIB$MOVTC and LIB$MOVTUC are described 
below. Each table is preceded by explanatory text. 

ASCII to EBCDIC Translation Table 

• The number on the left represents the low-order bits of the ASCII 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 

Table RTL-6 LIB$AB_ASC_EBC 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

40 

F0 

7C 

D7 

79 

97 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

1 

01 

11 

4F 

FI 

Cl 

D8 

81 

98 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

2 

02 

12 

7F 

F2 

C2 

D9 

82 

99 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3 

03 

13 

7B 

F3 

C3 

E2 

83 

A2 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

4 

37 

3C 

5B 

F4 

C4 

E3 

84 

A3 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

5 

2D 

3D 

6C 

F5 

C5 

E4 

85 

A4 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

6 

2E 

32 

50 

F6 

C6 

E5 

86 

A5 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

7 

2F 

26 

7D 

F7 

C7 

E6 

87 

A6 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

8 

16 

18 

4D 

F8 

C8 

E7 

88 

A7 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

9 

05 

19 

5D 

F9 

C9 

E8 

89 

A8 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

A 

25 

3F 

5C 

7A 

D1 

E9 

91 

A9 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

B 

0B 

27 

4E 

5E 

D2 

4A 

92 

CO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

C 

OC 

1C 

6B 

4C 

D3 

E0 

93 

6A 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

D 

0D 

ID 

60 

7E 

D4 

5A 

94 

DO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

E 

0E 

IE 

4B 

6E 

D5 

5F 

95 

A1 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

F 

OF 

IF 

61 

6F 

D6 

6D 

96 

07 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

FF 
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ASCII to EBCDIC Reversible Translation Table 

• The number on the left represents the low-order bits of the ASCII 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 

Table RTL-7 LIB$AB_ASC_EBC_REV 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

40 

F0 

7C 

D7 

79 

97 

20 

30 

41 

58 

76 

9F 

B8 

DC 

1 

01 

11 

4F 

FI 

Cl 

D8 

81 

98 

21 

31 

42 

59 

77 

A0 

B9 

DD 

2 

02 

12 

7F 

F2 

C2 

D9 

82 

99 

22 

1A 

43 

62 

78 

AA 

BA 

DE 

3 

03 

13 

7B 

F3 

C3 

E2 

83 

A2 

23 

33 

44 

63 

80 

AB 

BB 

DF 

4 

37 

3C 

5B 

F4 

C4 

E3 

84 

A3 

24 

34 

45 

64 

8A 

AC 

BC 

EA 

5 

2D 

3D 

6C 

F5 

C5 

E4 

85 

A4 

15 

35 

46 

65 

8B 

AD 

BD 

EB 

6 

2E 

32 

50 

F6 

C6 

E5 

86 

A5 

06 

36 

47 

66 

8C 

AE 

BE 

EC 

7 

2F 

26 

7D 

F7 

C7 

E6 

87 

A6 

17 

08 

48 

67 

8D 

AF 

BF 

ED 

8 

16 

18 

4D 

F8 

C8 

E7 

88 

A7 

28 

38 

49 

68 

8E 

B0 

CA 

EE 

9 

05 

19 

5D 

F9 

C9 

E8 

89 

A8 

29 

39 

51 

69 

8F 

B1 

CB 

EF 

A 

25 

3F 

5C 

7A 

D1 

E9 

91 

A9 

2A 

3A 

52 

70 

90 

B2 

CC 

FA 

B 

0B 

27 

4E 

5E 

D2 

4A 

92 

CO 

2B 

3B 

53 

71 

9A 

B3 

CD 

FB 

C 

OC 

1C 

6B 

4C 

D3 

E0 

93 

6A 

2C 

04 

54 

72 

9B 

B4 

CE 

FC 

D 

0D 

ID 

60 

7E 

D4 

5A 

94 

DO 

09 

14 

55 

73 

9C 

B5 

CF 

FD 

E 

0E 

IE 

4B 

6E 

D5 

5F 

95 

A1 

0A 

3E 

56 

74 

9D 

B6 

DA 

FE 

F 

OF 

IF 

61 

6F 

D6 

6D 

96 

07 

IB 

El 

57 

75 

9E 

B7 

DB 

FF 
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EBCDIC to ASCII Translation Table 

• The number on the left represents the low-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 
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Table RTL-8 LIB$AB_EBC_ASC 


Row 

bits 0-3 




Column 



bits 4 - 

■ 7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

5C 

5C 

20 

26 

2D 

5C 

5C 

5C 

5C 

5C 

7B 

7D 

5C 

30 

1 

01 

11 

5C 

5C 

5C 

5C 

2F 

5C 

61 

6A 

7E 

5C 

41 

4A 

5C 

31 

2 

02 

12 

5C 

16 

5C 

5C 

5C 

5C 

62 

6B 

73 

5C 

42 

4B 

53 

32 

3 

03 

13 

5C 

5C 

5C 

5C 

5C 

5C 

63 

6C 

74 

5C 

43 

4C 

54 

33 

4 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

64 

6D 

75 

5C 

44 

4D 

55 

34 

5 

09 

5C 

0A 

5C 

5C 

5C 

5C 

5C 

65 

6E 

76 

5C 

45 

4E 

56 

35 

6 

5C 

08 

17 

5C 

5C 

5C 

5C 

5C 

66 

6F 

77 

5C 

46 

4F 

57 

36 

7 

7F 

5C 

IB 

04 

5C 

5C 

5C 

5C 

67 

70 

78 

5C 

47 

50 

58 

37 

8 

5C 

18 

5C 

5C 

5C 

5C 

5C 

5C 

68 

71 

79 

5C 

48 

51 

59 

38 

9 

5C 

19 

5C 

5C 

5C 

5C 

5C 

60 

69 

72 

7A 

5C 

49 

52 

5A 

39 

A 

5C 

5C 

5C 

5C 

5B 

5D 

7C 

3A 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

B 

0B 

5C 

5C 

5C 

2E 

24 

2C 

23 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

C 

OC 

1C 

5C 

14 

3C 

2A 

25 

40 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

D 

0D 

ID 

05 

15 

28 

29 

5F 

27 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

E 

0E 

IE 

06 

5C 

2B 

3B 

3E 

3D 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

F 

OF 

IF 

07 

1A 

21 

5E 

3F 

22 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

FF 
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EBCDIC to ASCII Reversible Translation Table 

• The number on the left represents the low-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 
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Table RTL-9 LIB$AB_EBC_ASC_REV 


Row 

bits 0-3 




Column 



bits 4 - 

- 7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

80 

90 

20 

26 

2D 

BA 

C3 

CA 

D1 

D8 

7B 

7D 

5C 

30 

1 

01 

11 

81 

91 

A0 

A9 

2F 

BB 

61 

6A 

7E 

D9 

41 

4A 

9F 

31 

2 

02 

12 

82 

16 

A1 

AA 

B2 

BC 

62 

6B 

73 

DA 

42 

4B 

53 

32 

3 

03 

13 

83 

93 

A2 

AB 

B3 

BD 

63 

6C 

74 

DB 

43 

4C 

54 

33 

4 

9C 

9D 

84 

94 

A3 

AC 

B4 

BE 

64 

6D 

75 

DC 

44 

4D 

55 

34 

5 

09 

85 

0A 

95 

A4 

AD 

B5 

BF 

65 

6E 

76 

DD 

45 

4E 

56 

35 

6 

86 

08 

17 

96 

A5 

AE 

B6 

CO 

66 

6F 

77 

DE 

46 

4F 

57 

36 

7 

7 F 

87 

IB 

04 

A6 

AF 

B7 

Cl 

67 

70 

78 

DF 

47 

50 

58 

37 

8 

97 

18 

88 

98 

A7 

B0 

B8 

C2 

68 

71 

79 

E0 

48 

51 

59 

38 

9 

8D 

19 

89 

99 

A8 

B1 

B9 

60 

69 

72 

7A 

El 

49 

52 

5A 

39 

A 

8E 

92 

8A 

9A 

5B 

5D 

7C 

3A 

C4 

CB 

D2 

E2 

E8 

EE 

F4 

FA 

B 

0B 

8F 

8B 

9B 

2E 

24 

2C 

23 

C5 

CC 

D3 

E3 

E9 

EF 

F5 

FB 

C 

OC 

1C 

8C 

14 

3C 

2A 

25 

40 

C6 

CD 

D4 

E4 

EA 

F0 

F6 

FC 

D 

0D 

ID 

05 

15 

28 

29 

5F 

27 

C7 

CE 

D5 

E5 

EB 

FI 

F7 

FD 

E 

0E 

IE 

06 

9E 

2B 

3B 

3E 

3D 

C8 

CF 

D6 

E6 

EC 

F2 

F8 

FE 

F 

OF 

IF 

07 

1A 

21 

5E 

3F 

22 

C9 

DO 

D7 

E7 

ED 

F3 

F9 

FF 
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Packed Decimal to Trailing Overpunch Numeric Translation Table 

• The number on the left represents the low-order bits of the packed decimal 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the packed 
decimal value in hexadecimal notation. 

• The number in the body of the table represents the equivalent trailing 
overpunch numeric value in hexadecimal notation. 
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Table RTL-10 LIB$AB_CVTPT_0 






Column 



bits 4 - 

7 






Row 

bits 0-3 

0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

7 B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

1 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

2 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

3 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

4 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

5 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

6 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

8 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

9 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

7B 

A 

7B 

41 

42 

43 

44 

45 

46 

47 

48 

49 

7B 

7B 

7B 

7B 

7B 

7B 

B 

7 D 

4A 

4B 

4C 

4D 

4E 

4F 

50 

51 

52 

7B 

7B 

7B 

7B 

7B 

7B 

C 

7B 

41 

42 

43 

44 

45 

46 

47 

48 

49 

7B 

7B 

7B 

7B 

7B 

7B 

D 

7 D 

4A 

4B 

4C 

4D 

4E 

4F 

50 

51 

52 

7B 

7B 

7B 

7B 

7B 

7B 

E 

7B 

41 

42 

43 

44 

45 

46 

47 

48 

49 

7B 

7B 

7B 

7B 

7B 

7B 

F 

7B 

41 

42 

43 

44 

45 

46 

47 

48 

49 

7B 

7B 

7B 

7B 

7B 

7B 
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Packed Decimal to Unsigned Trailing Numeric Translation Table 

• The number on the left represents the low-order bits of the packed decimal 
value in hexadecimal notation. 

• The number across the top represents the high-order bits of the packed 
decimal value in hexadecimal notation. 

• The number in the body of the table represents the equivalent unsigned 
trailing numeric value in hexadecimal notation. 
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Table RTL-11 LIB$AB_CVTPT_U 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

c 

D 

E 

F 

0 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

1 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

2 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

3 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

4 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

5 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

6 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

7 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

8 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

9 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

A 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 

B 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 

C 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 

D 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 

E 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 

F 

30 

31 

32 

33 

34 

35 

36 

37 

38 

39 

00 

00 

00 

00 

00 

00 
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Trailing Overpunch Numeric to Packed Decimal Translation Table 

• The number on the left represents the low-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number across the top represents the high-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent packed 
decimal value in hexadecimal notation. 
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Table RTL-12 LIB$AB_CVTTP_0 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

c 

D 

E 

F 

0 

00 

00 

00 

oc 

00 

7D 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

1 

00 

00 

0D 

1C 

1C 

8D 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

2 

00 

00 

00 

2C 

2C 

9D 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

3 

00 

00 

00 

3C 

3C 

00 

00 

00 

00 

00 

00 

00 

00 
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00 

F 

00 

00 

00 
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6D 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 
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Unsigned Numeric to Packed Decimal Translation Table 

• The number on the left represents the low-order bits of the unsigned 
numeric value in hexadecimal notation. 

• The number across the top represents the high-order bits of the unsigned 
numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent packed 
decimal value in hexadecimal notation. 
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Table RTL-13 LIB$AB_CVTTP_U 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

c 

D 

E 

F 

0 

00 

00 

00 

oc 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

1 

00 

00 

00 

1C 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

2 

00 

00 

00 

2C 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

3 

00 

00 

00 

3C 

00 

00 

00 

00 

00 
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00 

00 

00 

8C 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

9 

00 

00 

00 

9C 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

A 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

B 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

C 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

D 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

E 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

F 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 

00 
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Trailing Overpunch Numeric to Unsigned Numeric Translation Table 

• The number on the left represents the low-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number across the top represents the high-order bits of the trailing 
overpunch numeric value in hexadecimal notation. 

• The number in the body of the table represents the equivalent unsigned 
numeric value in hexadecimal notation. 
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CONDITION 

VALUES 

RETURNED 


Table RTL-14 LIB$AB_CVT_Q_U 


Row 

bits 0-3 




Column 



bits 4 - 

- 7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

20 

30 

40 

37 

60 

70 

80 

90 

A0 

B0 

CO 

DO 

E0 

F0 

1 

01 

11 

30 

31 

31 

38 

61 

71 

81 

91 

A1 

B1 

Cl 

D1 

El 

FI 

2 

02 

12 

22 

32 

32 

39 

62 

72 

82 

92 

A2 

B2 

C2 

D2 

E2 

F2 

3 

03 

13 

23 

33 

33 

53 

63 

73 

83 

93 

A3 

B3 

C3 

D3 

E3 

F3 

4 

04 

14 

24 

34 

34 

54 

64 

74 

84 

94 

A4 

B4 

C4 

D4 

E4 

F4 

5 

05 

15 

25 

35 

35 

55 

65 

75 

85 

95 

A5 

B5 

C5 

D5 

E5 

F5 

6 

06 

16 

26 

36 

36 

56 

66 

76 

86 

96 

A6 

B6 

C6 

D6 

E6 

F6 

7 

07 

17 

27 

37 

37 

57 

67 

77 

87 

97 

A7 

B7 

C7 

D7 

E7 

F7 

8 

08 

18 

28 

38 

38 

58 

68 

78 

88 

98 

A8 

B8 

C8 

D8 

E8 

F8 

9 

09 

19 

29 

39 

39 

59 

69 

79 

89 

99 

A9 

B9 

C9 

D9 

E9 

F9 

A 

0A 

1A 

2A 

30 

31 

5A 

6A 

7A 

8A 

9A 

AA 

BA 

CA 

DA 

EA 

FA 

B 

0B 

IB 

2B 

3B 

32 

30 

6B 

30 

8B 

9B 

AB 

BB 

CB 

DB 

EB 

FB 

C 

OC 

1C 

2C 

3C 

33 

5C 

6C 

7C 

8C 

9C 

AC 

BC 

CC 

DC 

EC 

FC 

D 

0D 

ID 

2D 

3D 

34 

30 

6D 

30 

8D 

9D 

AD 

BD 

CD 

DD 

ED 

FD 

E 

0E 

IE 

2E 

3E 

35 

5E 

6E 

7E 

8E 

9E 

AE 

BE 

CE 

DE 

EE 

FE 

F 

OF 

IF 

2F 

30 

36 

5F 

6F 

7F 

8F 

9F 

AF 

BF 

CF 

DF 

EF 

FF 


ZK-4255-85 


Unsigned Numeric to Trailing Overpunch Translation Table 

Table RTL-15 is indexed by 0 through 9 for the positive overpunches and 10 
through 19 for the negative overpunches. 

The unsigned binary representation of the least significant digit is moved into 
R2. Then, if you require a positive result, the following code results: 

M0VC3 LIB$AB_CVT_U_0[R2] , #1,R0 

If you require a negative result, the following code is generated: 

M0VC3 LIB$AV_CVT_U_0 + 10[R2]. #1,R0 

The result is the overpunch representation for the last byte of the negative 
number. 

Table RTL-15 LIB$AB_CVT_U-0 


o 

1 

vD 

10-19 

7B 41 42 43 44 45 46 47 48 49 

7D 4A 4B 4C 4D 4E 4F 50 51 52 
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SS$_NORMAL Procedure successfully completed. 

LIB$_STRTRU Procedure successfully completed; string truncated. 

The fixed-length destination string could not 
contain all the characters. 
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LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Fatal internal error. 
Insufficient virtual memory. 
Invalid string descriptor. 


EXAMPLE 

1 ! + 

IThis program illustrates the method 

!of creating a descriptor for the appropriate 

{translation table in order to call LIB$M0VTC. 

i - 

OPTION TYPE = EXPLICIT 
! + 

{Declare the translation table as an 
{EXTERNAL LONG variable. 

; - 

EXTERNAL LONG LIB$AB_ASC_EBC 
EXTERNAL LONG FUNCTION LIB$M0VTC 
EXTERNAL SUB LIB$ST0P 

EXTERNAL LONG CONSTANT DSC$K_CLASS_S, DSC$K_DTYPE_T 
{+ 

{Define a record which models the required 
{translation table descriptor. 

I _ 

RECORD STR.TYPE 

BYTE DSC$B_CLASS 
BYTE DSC$B_DTYPE 
WORD DSC$W_LENGTH 
LONG DSC$A_POINTER 
END RECORD STR.TYPE 

DECLARE LONG I, RET.STS 
DECLARE STR.TYPE STR.VAR 

MAP (F00) STRING DST = 37. 

MAP (F00) BYTE DST_ARRAY(2) 

{+ 

{Fill the translation table descriptor record. 

{Note that the length of the translation table string 
Sis set to 256, and the pointer receives the address of 
!the DIGITAL translation table LIB$AB_ASC_EBC. 

i - 

STR.VAR::DSC$B_CLASS = DSC$K_CLASS_S 
STR.VAR::DSC$B_DTYPE = DSC$K_DTYPE_T 
STR.VAR::DSC$W_LENGTH = 256 
STR.VAR::DSC$A_POINTER = LOC(LIB$AB_ASC_EBC) 

RET.STS = LIB$M0VTC( "ABC". " ", STR.VAR BY REF, DST ) 
IF (RET.STS AND iy.) = Oy. 

THEN 

CALL LIBISTOPC RET.STS BY VALUE ) 

END IF 

{♦ 

{Add 256 to the translated value in order to return 
!an unsigned value. 

i - 

PRINT (256 ♦ DST.ARRAY (I)) FOR I = 07. TO 27. 

END 
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The output generated by this program is as follows: 

193 

194 

195 
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LIB$MOVTUC—Move Translated Until 

Character 


LIB$MOVTUC moves the source string, character by character, 
to the destination string after translating each character using the 
specified translation table until the stop character is encountered. 
LIB$MOVTUC makes the VAX MOVTUC instruction available as a 
callable procedure. 

FORMAT 

LIB$MOVTUC src-str,stop-char , trans-tbl,dst-str 
[, fill-char] 

RETURNS 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by value 


The relative position in the source string of the character that is translated to 
the stop character. Zero is returned if the stop character is not found. This 
value is set to -1 if dst-str cannot be allocated. 


ARGUMENTS 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be translated and moved by LIB$MOVTUC. The src-str 
argument is the address of a descriptor pointing to this source string. 


stop-char 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Stop character that causes LIB$MOVTUC to stop translating the source string. 
The stop-char argument is the address of a descriptor pointing to a string. 
The first character of this string is used as the stop character. The length of 
this string is not checked and stop-char is not translated. 


trans-tbl 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Translation table used by LIB$MOVTUC. The trans-tbl argument is the 
address of a descriptor pointing to the translation table string. The translation 
table string is assumed to be 256 characters long. 
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You can use any of the translation tables included in the Description section 
of LIB$MOVTC, or you can create your own. When using a translation table 
supplied by DIGITAL, the names LIB$AB_xxx_yyy represent the addresses 
of the 256 byte translation tables, and can be accessed as external (string) 
variables. If a particular language cannot generate descriptors for external 
strings, then they must be created manually. The example for the routine 
LIB$MOVTC illustrates the creation of a string descriptor for a translation 
table using VAX BASIC. 


dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$MOVTUC writes the translated src-str. The 
dst-str argument is the address of a descriptor pointing to this destination 
string. 


fill-char 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Character used to pad src-str to the length of dst-str. The fill-char argument 
is the address of a descriptor pointing to a string. The first character of this 
string is used as the fill character. The length of this string is not checked and 
fill-char is not translated. 


If the fill character is included, the remainder of the destination string 
(after the stop character) is filled with the specified fill character. If it is 
not included, the remainder of the destination string remains unchanged. 


DESCRIPTION During the translation, LIB$MOVTUC accesses each character in the source 

string and uses it as an index into the translation table. If the table entry 
contains the specified stop character, the routine is terminated and the relative 
position of the source character is returned. 

If the source string is longer than the destination string, then the source string 
is truncated. If the optional fill character is present, any remaining positions 
in the destination string are filled with the fill character. If the source or 
destination string is exhausted (before the stop character is found), a zero 
index is returned. 

The results are unpredictable if the source and destination strings overlap and 
have different starting addresses. 

See the description of LIB$MOVTC for the translation tables used by 
LIB$MOVTC and LIB$MOVTUC. Each translation table is preceded by 
explanatory text. 


CONDITION None. 

VALUES 

RETURNED 
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LIB$PAUSE—Pause Program Execution 



LIB$PAUSE suspends program execution and returns control to the 
calling command level. 

FORMAT 

LIBSPAUSE 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

None. 

DESCRIPTION 

LIB$PAUSE suspends program execution and returns control to the 
calling command level. The suspended image may be continued with the 
CONTINUE command, or it may be terminated with the EXIT or STOP 
commands. In the latter case, the image will not return to this routine. 

Note that this routine functions only for interactive jobs. If this routine is 
invoked in batch mode, it has no effect. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

LIB$_NOCLI No CLI present. The calling process does not have 

a CLI or the CLI does not support the request. 

Note that DCL only supports this function in 
INTERACTIVE mode. 


RTL-228.2 


April 1986 











Run-Time Library Routines 

LIB$POLYz 


LIB$POLYz—Evaluate Polynomials 



LIB$POLYF, LIB$POLYD, LIB$POLYG, and LIB$POLYH allow higher- 
level language users to evaluate polynomials. These procedures 
use the VAX hardware instructions POLYF, POLYD, POLYG, and 
POLYH. 

FORMAT 

LIB$POLYF arg,degree ,coeff,result 

LIB$POLYD arg,degree ,coeff,result 

LI B$POLYG arg, degree, coeff,result 

LIB$POLYH arg,degree ,coeff,result 

Each of the above four formats accepts as input one of the four floating-point 
types. 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

arg 

VMS Usage: floating-point 

type: F_floating, D_floating, G_ floating, H_floating 

access: read only 

mechanism: by reference 

Argument for the polynomial. The arg argument is the address of a 
floating-point number that contains this argument. For LIB$POLYF, arg is 
an F_floating number. For LIB$POLYD, arg is a D—floating number. For 
LIB$POLYG, arg is a G_floating number. For LIB$POLYH, arg is an 
H_floating number. 

degree 

VMS Usage: word-signed 

type: word integer (signed) 

access: read only 

mechanism: by reference 

Highest numbered non-zero coefficient to participate in the evaluation. The 
degree argument is the address of a signed word integer that contains this 
highest-numbered coefficient. 

If the degree is 0, the result equals C[0]. The range of the degree is 0 to 31. 

coeff 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: read only 

mechanism: by reference, array reference 

Floating-point coefficients. The coeff argument is the address of an array of 
floating-point coefficients. The coefficient of the highest-order term of the 
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polynomial is the lowest-addressed element in the array. For LIB$POLYF, 
coeff is an array of F_floating numbers. For LIB$POLYD, coeff is an array 
of D_floating numbers. For LIB$POLYG, coeff is an array of G_floating 
numbers. For LIB$POLYH, coeff is an array of FLJloating numbers. 

result 

VMS Usage: floating-point 

type: F_floating, D_floating, G_floating, H_floating 

access: write only 

mechanism: by reference 

Result of the calculation. The result argument is the address of a floating¬ 
point number that contains this result. LIB$POLYF writes the address of 
result into an F_floating number. LIB$POLYD writes the address of result 
into a D_floating number. LIB$POLYG writes the address of result into a 
G_floating number. LIB$POLYH writes the address of result into an 
H_floating number. 

Intermediate multiplications are carried out using extended floating-point 
fractions (31 bits for POLYF, 63 bits for POLYD and POLYG, and 127 bits for 
POLYH). 

DESCRIPTION 

LIB$POLYF, LIB$POLYD, LIB$POLYG, and LIB$POLYH provide higher- 
level language users with the capability of evaluating polynomials. These 
procedures use the VAX hardware instructions POLYF, POLYD, POLYG, and 
POLYH. 

The evaluation is carried out by Homer's Method. The result is computed as 
follows: 

result = C[0]+X*(C[1]+X*(C[2] ♦ ...X*(C[D])...)) 

In the above result D is the degree of the polynomial and X is the argument. 

See the VAX-11 Architecture Reference Manual for the detailed description of 
POLY. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

SS$_FLTUND Floating underflow. After rounding, the 

intermediate result is replaced by zero and 
the operation continues. If both overflow and 
underflow occur in the same instruction, the 
underflow condition is lost. 

SS$_ROPRAND Reserved operand. 


EXAMPLES 

Q c* 

C This FORTRAN example demonstrates how to use 
C LIB$POLYF. 

C- 

REAL*4 X , COEFF(5),RESULT 
INTEGER*2 DEG 
C+ 

C Compute X~4 + 2*X~3 -X~2 + X - 3 using POLYF 
C Let X = 2. 

C The coefficients needed are as follows: 
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c- 

DATA COEFF/i.0,2.0,-1.0,1.0,-3.0/ 

X = 2.0 

DEG = 4 ! DEG has word length. 

C+ 

C Calculate (2)“4 + 2 * (2~3) -2~2 +2-3. 

C The result should be 27. 

C- 

RETURN = LIB$POLYF(X,DEG,COEFF,RESULT) 

TYPE *,'(2)~4 + 2 * (2*3) -2~2 + 2 - 3 = '.RESULT 
END 


This FORTRAN example demonstrates how to call LIB$POLYF. The output 
generated by this program is as follows: 

(2)~4 + 2*(2~3) -2~2 + 2 - 3 * 27.00000 


E PROGRAM POLYF(INPUT,OUTPUT); 

<♦> 

{ This PASCAL program demonstrates how to use 
{ LIBlPOLYF to evaluate a polynomial. 

<-> 


TYPE 

WORD = [WORD] 0..65535; 

VAR 

COEFF : ARRAY [0..2] OF REAL :* (1.0,2.0,2.0); 

RESULT : REAL; 

RETURNED.STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$P0LYF( 

ARG : REAL; 

DEGREE : WORD; 

COEFF : [REFERENCE] ARRAY [L..U:INTEGER] OF REAL; 

VAR RESULT : REAL 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION.STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
FAO.ARGS : [IMMEDIATE,UNSAFE.LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 


BEGIN 

{+> 

{ Call LIBIPOLYF to evaluate 2(X**2) + 2*X + 1. 
{-> 

RETURNED.STATUS := LIB$POLYF(1.0,2,COEFF,RESULT); 
IF NOT ODD(RETURNED.STATUS) 

THEN 

LIBISTOP(RETURNED.STATUS); 

WRITELN('F(1.0) = '.RESULT:5:2); 

END. 


This example program demonstrates how to call LIB$POLYF from PASCAL. 
The output generated by this PASCAL program is as follows: 

$ RUN POLYF 
F(l.O) = 5.00 
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LI B$ PUT_.COM MON—Put String to 

Common 



LIB$PUT_COMMON copies the contents of a string into the 
common area. The common area is an area of storage which 
remains defined across multiple image activations in a process. 
Optionally, LIB$PUT_COMMON returns the actual number of 
characters copied. The maximum number of characters that can be 
copied is 252. 

FORMAT 

LI B$ PUT_C O M M O N src-str [, chars-copied] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be copied to the common area by LIB$PUT_COMMON. The 
src-str argument is the address of a descriptor pointing to this source string. 

chars-copied 

VMS Usage: word_signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of characters copied by LIB$PUT_COMMON to the common area. 
The chars-copied argument is the address of a signed word integer that 
contains this number of characters. LIB$PUT_COMMON writes this number 
into the chars-copied argument. 

DESCRIPTION 

LIB$PUT_COMMON and LIB$GET_COMMON allow programs to copy 
strings to and from the common area. The programs reading and writing 
the data in the common area must agree upon its amount and format. The 
maximum length of the destination string is defined as follows: 

[min(256, the length of the data in the common storage area) - 4] 

Thus, maximum length is 252. 

In BASIC and FORTRAN, you can use these procedures to allow a 
USEROPEN procedure to pass information back to the procedure that 
called it. A USEROPEN procedure cannot write arguments. However, it can 
call LIB$PUT_COMMON to put information into the common area. The 
calling program can then use LIB$GET_COMMON to retrieve it. 
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CONDITION 

VALUES 

RETURNED 


You can also use these procedures to pass information between images run 
successively, such as chained images run by LIB$RUN_PROGRAM. 


SSS—NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Successfully completed, but the source string was 
truncated. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$PUT_OUTPUT—Put Line to 



SY S$OUTPUT 

LIB$PUT_OUTPUT writes a record to the current controlling output 
device, specified by SYS$OUTPUT using the VAX RMS $PUT 
service. 

FORMAT 

LIB$PUT_OUTPUT msg-str 

RETURNS 

VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

msg-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Message string written to the current controlling output device by LIB$PUT_ 
OUTPUT. The msg-str argument is the address of a descriptor pointing to 
this message string. VAX RMS handles all formatting, so the message does 
not need to include such ASCII formatting instructions as carriage return 
(CR). 

DESCRIPTION 

When you log in, VAX/VMS creates three files as default I/O control streams 
for your process. 

• SYS$INPUT, your default input device 

• SYS$OUTPUT, your default output device 

• SYS$COMMAND, the device that supplies the commands to your process 

These files remain open until you log out. They are the interface between 
your interactive input and output or batch commands and the VAX/VMS 
software. Initially, all three are equated with the terminal. However, with 
the DCL ASSIGN command, you can change these assignments to obtain 
information from a file or put information into a file. SYS$INPUT and 
SYS$COMMAND are usually identical, but the input and command streams 
can be different. For example, during the execution of an indirect command 
file from an interactive terminal, SYS$COMMAND refers to the terminal and 
SYS$INPUT refers to the command file. 

On the first call to LIB$PUT_OUTPUT, if the output file is not a process- 
permanent file, LIB$PUT_OUTPUT opens the output file and positions it 
at the end-of-file mark. If no output file exits on the first call, LIB$PUT_ 
OUTPUT creates a file. The VAX RMS internal stream identifier (ISI) is stored 
in the procedure's static storage for subsequent calls. Hence, this procedure is 
not AST reentrant. 
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LIB$PUT_OUTPUT uses VAX RMS to format records on output, and RMS 
records have implied carriage control. That is, a record normally corresponds 
to a line of text. Therefore, if you want explicit carriage control, instead of 
implied carriage control, you must supply it yourself within the source string. 

LIB$PUT_OUTPUT is the most convenient way for a MACRO or BLISS 
program to write information to SYS$OUTPUT. 

If you have several shareable images that call LIB$PUT_OUTPUT, and if 
each shareable image includes its own copy of LIB$PUT_OUTPUT, your 
program could produce multiple output streams and multiple versions of your 
output file. A single application should reference one copy of LIB$PUT_ 
OUTPUT. 


CONDITION 

VALUES 

RETURNED 


EXAMPLE 


SSS—NORMAL Routine successfully completed. 

Any condition values returned by RMS. 


10 ! ♦ 

! This BASIC program demonstrates how to use 
! LIB$PUT_0UTPUT to output a simple message. 

i - 

MSGSTR$ = 'This is a sample message' 

CALL LIB$PUT_0UTPUT(MSGSTR$) 
t + 

! In this example, the default value of 
! SYSIOUTPUT is used. Therefore, the 
! output is 'put' to the terminal screen. 

j - 

90 END 


This BASIC program illustrates the use of LIB$PUT_OUTPUT. The output 
generated by this BASIC example is as follows: 

This is a sample message 
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LIB$RADIX_POINT—Radix Point Symbol 



LIB$RADIX_POINT returns the system's radix point symbol. This 
symbol is used inside a digit string to separate the integer part from 
the fraction part. This routine works by attempting to translate the 
logical name SYS$RADIX_POINT as a process, group, or system 
logical name. 

FORMAT 

LI B$RADIX_POI NT radix-point-str[,out-len] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

radix-point-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Radix point string. The radix-point-str argument is the address of a 
descriptor pointing to this radix point string. 

out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

The number of characters written into radix-point-str, not counting padding 
in the case of a fixed-length string. The out-len argument is the address of 
an unsigned word that contains this number. 

If the radix-point-str argument is the address of a fixed-length string 
descriptor, there may not be enough characters in the fixed-length string to 
contain the whole radix point string, and the radix point string is truncated. If 
the radix point string is truncated to the size specified in a fixed-length string 
descriptor, out-len is set to this size. Therefore, out-len can always be used 
by the calling program to access a valid substring of radix-point-str. 

DESCRIPTION 

If unable to translate the logical name SYS$RADIX_POINT, LIB$RADIX__ 
POINT returns the United States radix point symbol (.). If the translation 
succeeds, the text produced is returned. Thus, a system manager can define 
SYS$RADIX_POINT as a system-wide logical name to provide a default for 
all users, and an individual user with a special need can define SYS$RADIX__ 
POINT as a process logical name to override the default. 

LIB$RADIX_POINT is used implicitly by BASIC. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIBS—INVSTRDES 


Procedure completed successfully. 

Successfully completed, but the radix point string 
was truncated. 

Fatal internal error. 

Insufficient virtual memory. 

Invalid string descriptor. 
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LIB$REMQHI—Remove Entry from Head 



of Queue 

LIB$REMQHI removes an entry from the head of the specified self¬ 
relative interlocked queue. LIB$REMQHI makes the VAX REMQHI 
instruction available as a callable procedure. 

FORMAT 

LIB$REMQHI header,remque-adr[,retry-cnt] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

header 

VMS Usage: quadword_signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference 

Queue header specifying the queue from which entry will be removed. 

The header argument contains the address of this signed aligned quadword 
integer. Header must be initialized to zero before first use of the queue; zero 
means an empty queue. 

remque-adr 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the removed entry. The remque-adr argument is the address of 
an unsigned longword that contains this address. If the queue was empty, 
remque-adr is set to the address of the header. 

retry-cnt 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The number of times the operation is to be retried in case of secondary- 
interlock failure of the queue instruction in a processor-shared memory 
application. The retry-cnt argument is the address of a longword that 
contains the retry count value. A value of 1 causes no retries. The default 
value is 10. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


The queue from which LIB$REMQHI removes an entry can be in process- 
private, processor-private, or processor-shareable memory to implement 
per-process, per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library procedure specifies a 
queue entry by its address. Two longwords, a forward link and a backward 
link, define the location of the entry in relation to the preceding and 
succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the 
current entry's predecessor and successor. The VAX instructions INSQHI 
and REMQHI allow you to insert and remove an entry at the head of a 
self-relative queue. The corresponding Run-Time Library procedures are 
LIB$INSQHI and LIB$REMQHI. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the 
current program is doing so. Since the operation requires changing two 
pointers at the same time, a high-level language cannot perform this 
operation without calling the Run-Time Library queue access procedures. 

When you use these procedures, cooperating processes can communicate 
without further synchronization and without danger of being interrupted, 
either on a single processor or in a multiprocessor environment. The queue 
access procedures are also useful in an AST environment; they allow you 
to add or remove an entry from a queue without being interrupted by an 
asynchronous system trap. 


SS$_NORMAL 

LIB$_ONEENTQUE 

LIB$_SECINTFAI 


LIB$_QUEWASEMP 

SS$_ROPRAND 


Routine successfully completed. The entry was 
removed from the head of the queue, and the 
resulting queue contains one or more entries. 

Procedure successfully completed. The entry was 
removed from the head of the queue, and the 
resulting queue is empty. 

A secondary interlock failure occurred; the insertion 
was attempted the number of times specified by 
retry-cnt. This is a severe error. The queue is not 
modified. This condition can occur only when the 
queue is in memory being shared between two or 
more processors. 

The queue was empty. The queue is not modified. 

Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 
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LIB$REMQTI—Remove Entry from Tail of 



Queue 

LIB$REMQTI removes an entry from the tail of the specified self¬ 
relative interlocked queue. LIB$REMQTI makes the VAX REMQTI 
instruction available as a callable procedure. 

FORMAT 

LIB$REMQTI header,remque-adr[,retry-cnt] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

header 

VMS Usage: quadword—signed 
type: quadword integer (signed) 

access: modify 

mechanism: by reference 

Queue header specifying the queue from which the entry is to be deleted. 

The header argument contains the address of this signed aligned quadword 
integer. Header must be initialized to zero before first use of the queue; zero 
means an empty queue. 

remque-adr 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Address of the removed entry. The remque-adr argument is the address of a 
longword that contains this address. If the queue was empty, remque-adr is 
set to the address of the header. 

retry-cnt 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

The number of times the operation is to be retried in case of secondary- 
interlock failure of the queue instruction in a processor-shared memory 
application. The retry-cnt argument is the address of a longword that is this 
retry count value. A value of 1 causes no retries. The default value is 10. 
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DESCRIPTION The queue from which LIB$REMQTI removes an in process-private, 

processor-private, or processor-shareable memory to implement per-process, 
per-processor, or across-processor queues. 

A queue is a doubly linked list. A Run-Time Library procedure specifies a 
queue entry by its address. Two longwords, a forward link and a backward 
link, define the location of the entry in relation to the preceding and 
succeeding entries. 

A self-relative queue is a queue in which the links between entries are 
displacements; the two longwords represent the displacements of the current 
entry's predecessor and successor. The VAX instructions INSQTI and 
REMQTI allow you to insert and remove an entry at the tail of a self-relative 
queue. The corresponding Run-Time Library procedures are LIB$INSQTI and 
LIB$REMQTI. 

The self-relative queue instructions are interlocked and cannot be interrupted, 
so that other processes cannot insert or remove queue entries while the 
current program is doing so. Since the operation requires changing two 
pointers at the same time, a high-level language cannot perform this 
operation without calling the Run-Time Library queue access procedures. 

When you use these procedures, cooperating processes can communicate 
without further synchronization and without danger of being interrupted, 
either on a single processor or in a multiprocessor environment. The queue 
access procedures are also useful in an AST environment; they allow you 
to add or remove an entry from a queue without being interrupted by an 
asynchronous system trap. 


CONDITION SSS—NORMAL 

VALUES 

SSS—ROPRAND 


LIB$_ONEENTQUE 

LIB$_QUEWASEMP 

LIB$_SECINTFAI 


Procedure successfully completed. The entry was 
removed from the queue tail, and the resulting 
queue contains one or more entries. 

Reserved operand fault. Either the entry or the 
header is at an address that is not quadword 
aligned, or the header address equals the entry 
address. 

Procedure successfully completed. The entry was 
removed from the queue tail, and the resulting 
queue is empty. 

Queue was empty. The queue is not modified. 

A secondary interlock failure occurred; the insertion 
was attempted the number of times specified by 
retry-cnt. This is a severe error. The queue is not 
modified. This condition can occur only when the 
queue is in memory being shared between two or 
more processors. 
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LIB$RENAME_FILE—Rename One or More 

Files 



LIB$RENAME_FILE changes the name(s) of one or more files. The 
specification of the file(s) to be renamed may include wildcards. 

LIB$RENAME_FILE is similar in function to the DCL command 
RENAME. 

FORMAT 

LIB$RENAME_FILE old-filespec ,new-filespec 

[, default-filespec] 

[, related-filespec] [, flags] 

[, success-routine] 

[, error-routine] 

[, confirm-routine] [, user-arg] 

[, old-resultant-name] 

[, new-resultant-name] 

[, file-scan-context] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

old-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification of the file(s) to be renamed. The old-filespec argument 
is the address of a descriptor pointing to the old file specification. The 
specification may include wildcards, in which case each file which matches 
the specification will be renamed. The string must not contain more than 255 
characters. Any string class is supported. 

new-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification for the new file name(s). The new-filespec argument is the 
address of a descriptor pointing to the new file specification. 

This specification need not be complete; fields omitted or specified by using 
the wildcard character (*) will be filled in from the existing file's name using 
the same rules as for the DCL command RENAME. The string must not 
contain more than 255 characters. Any string class is supported. 
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default-filespec 

VMS Usage: char__string 
type: character string 

access: read only 

mechanism: by descriptor 

Default file specification of the file(s) to be renamed. The default- 
filespec argument is the address of a descriptor pointing to the default 
file specification. 


This is an optional argument; if omitted, the default is the null string. See the 
VAX Record Management Services Reference Manual for information on default 
file specifications. The string must not contain more than 255 characters. Any 
string class is supported. 


related-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Related file specification of the file(s) to be renamed. The related- 
filespec argument is the address of a descriptor pointing to the related 
file specification. This is an optional argument; if omitted, the default is the 
null string. Any string class is supported. 


Input file parsing is used. (See the VAX Record Management Services Reference 
Manual for information on related file specifications and input file parsing.) 

The related file specification is useful when you are processing lists of file 
specifications. Unspecified portions of the file specification are inherited from 
the last file processed. Any string class is supported. This is an optional 
argument. 


flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Longword of flag bits designating optional behavior. The flags argument 
is the address of an unsigned longword containing the flag bits. This is an 
optional argument; if omitted, the default is that all flags are clear. 

The bit number, symbol, and its meaning is as follows: 


Bit Description 

0 If new-filespec does not specify a version number, this flag controls 

whether a new version number for the output file is to be assigned. If clear, 
the file is given a version number 1 higher than any previously existing 
file of the same file name and file type. This is the default action. If set, 
the current version number of the file is used. If a file already exists with 
the same file name, type and version number, the error RMS$_FEX is 
given. This flag is equivalent to the /NONEW_VERSION qualifier of the DCL 
RENAME command. 
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success-routine 


VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied success routine that LIB$RENAME_FILE calls after each 
successful rename. The success-routine argument is the address of the entry 
mask to the success routine. 


For further information on the success routine, see "Call Format for a Success 
Routine" in the Description section. 


error-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied error routine that LIB$RENAME_FILE calls when it detects an 
error. The error-routine argument is the address of the entry mask to the 
error routine. The value returned by the error routine determines whether 
LIB$RENAME_FILE processes more files. For further information on the 
error routine, see "Call Format for an Error Routine" in the Description 
section. 


confirm-routine 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference 

User-supplied confirm routine that LIB$RENAME_FILE calls before it 
renames a file. The confirm-routine argument is the address of the entry 
mask to the confirm routine. The value returned by the confirm routine 
determines whether or not LIB$RENAME_FILE renames the file. 

The confirm routine can be used to select specific files for renaming based on 
criteria such as expiration date, size, and so on. 

For further information on the confirm routine, see "Call Format for a Confirm 
Routine" in the Description section. 


user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value that LIB$RENAME_FILE passes to the success, error and confirm 
routines each time they are called. Whatever mechanism is used to pass 
user-arg to LIB$RENAME_FILE is also used to pass it to the user-supplied 
routines. This is an optional argument; if omitted, zero is passed by value. 


old-resultant-name 

VMS Usage: char_string 
type: character string 

access: write only 
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mechanism: by descriptor 

String into which LIB$RENAME_FILE copies the old resultant file 
specification of the last file processed. This is an optional argument. If 
present, it is used to store the file specification passed to the user-supplied 
routines instead of a default class S, type T string. Any string class is 
supported. 


new-resultant-name 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

String into which LIB$RENAME_FILE writes the new RMS resultant file 
specification of the last file processed. The new-resultant-name argument 
is the address of a descriptor pointing to the new name. This is an optional 
argument. If present, it is used to store the file specification passed to the 
user-supplied routines instead of a class S, type T string. Any string class is 
supported. 


file-scan-context 

VMS Usage: context 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

Context for renaming a list of filespecs. The file-scan-context is the 
address of a longword which contains this context. You must initialize this 
longword to zero before the first of a series of calls to LIB$RENAME_FILE. 
LIB$RENAME_FILE uses the file scan context to retain the file context for 
multiple input files. 


LIB$FILE_SCAN uses this context to retain multiple input file related file 
context. This is an optional argument; it need only be specified if you are 
using multiple input files, as the DCL command RENAME does. You may 
deallocate the context allocated by LIB$FILE_SCAN while processing the 
LIB$RENAME_FILE requests by calling LIB$FILE_SCAN_END after all 
calls to LIB$RENAME_FILE have been completed. See the description of 
LIB$FILE_SCAN for a more detailed description of this argument. 


DESCRIPTION This description is divided into three parts. 

• Call Format for a Success Routine 

• Call Format for an Error Routine 

• Call Format for a Confirm Routine 

Call Format for a Success Routine 

The success routine is optional; it is called only if the success-routine 
argument is specified in the call to LIB$RENAME_FILE. 

The calling format of a success routine is as follows: 

•uccaas-routina old-filespec ,new-filespec [,user-arg] 
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old-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: descriptor 

RMS resultant file specification of the file before it was renamed. If old- 
resultant-name was specified, it is used to pass the string to the success 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 

new-filespec 
VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

RMS resultant file specification of the newly renamed file. If new-resultant- 
name was specified, it is used to pass the string to the success routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value of user-arg passed by LIB$RENAME_FILE to the success routine using 
the same passing mechanism that was used to pass it to LIB$RENAME_FILE. 

Call Format for an Error Routine 

The error routine returns a success/fail value that LIB$RENAME__FILE 
uses to determine whether or not more files will be processed if an error is 
encountered. The error routine is called only if the error-routine argument 
was specified in the call to LIB$RENAME_FILE. If the error-routine 
argument was not specified, the default is to continue processing. 

The calling format of the error routine is as follows: 

•rror-routin« old-filespec .new-filespec .rms-sts ,rms-stv .error-source .user-arg 


old-filespec 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

RMS resultant file specification of the file being renamed when the error 
occurred. If old-resultant-name was specified, it is used to pass the string 
to the error routine. Otherwise, a class S, type T string is passed. Any string 
class is supported. 

new-filespec 
VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

RMS resultant file specification of the new file name being used when the 
error occurred. If new-resultant-name was specified, it is used to pass the 
string to the error routine. Otherwise, a class S, type T string is passed. Any 
string class is supported. 
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rms-sts 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
read only 
by reference 


Primary condition code (FAB$L_STS) which describes the error that occurred. 
The rms-sts argument is the address of an unsigned longword that contains 
this primary condition code. 


rms-stv 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Secondary condition code (FAB$L_STV) which describes the error that 
occurred. The rms-stv argument is the address of an unsigned longword that 
contains this secondary condition code. 


error-source 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Integer code indicating where the error was found. The error-source 
argument is the address of a longword containing the error source. 


The values of error-source and their meanings are as follows: 
0 Error searching for old-filespec 

1 Error parsing new-filespec 

2 Error renaming file 


user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value of user-arg that LIB$RENAME_FILE passes to the error routine using 
the same passing mechanism that was used to pass it to LIB$RENAME_FILE. 

If the error routine returns a success status (bit 0 set), then LIB$RENAME_ 
FILE will continue processing files. If the error routine returns a failure status 
(bit 0 clear), processing ceases immediately and LIB$RENAME_FILE returns 
with an error status. 

If the error-routine argument is not specified, LIB$RENAME_FILE will 
return to its caller the most severe error status encountered while renaming 
the files. If the error routine is called for an error, the success status LIB$_ 
ERRROUCAL is returned. 

The error routine is not called for errors related to string copying. 

Call Format for a Confirm Routine 

The calling format of a confirm routine is as follows: 

coniirm-routin* old-filespec ,new-filespec .old-lab [.user-arg] 


RTL-247 





Run-Time Library Routines 

LIB$RENAME_FILE 



old-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

RMS resultant file specification of the file about to be renamed. If old- 
resultant-name was specified, it is used to pass the string to the confirm 
routine. Otherwise, a class S, type T string is passed. Any string class is 
supported. 

new-filespec 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

RMS resultant file specification which the file will be given. If new-resultant- 
name was specified, it is used to pass the string to the confirm routine. 
Otherwise, a class S, type T string is passed. Any string class is supported. 

old-fab 

VMS Usage: fab 
type: unspecified 

access: read only 

mechanism: by reference 

Address of the RMS FAB that describes the file being renamed. Your program 
may perform an RMS $OPEN on the FAB to obtain file attributes it needs to 
determine whether the file should be renamed, but must close the file with 
$CLOSE before returning to LIB$RENAME_FILE. 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Value of user-arg passed by LIB$RENAME_FILE to the confirm routine using 
the same passing mechanism that was used to pass it to LIB$RENAME_FILE. 
This is an optional argument. 

If the confirm routine returns a success value (bit 0 set), the file is renamed; 
otherwise, the file is not renamed. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Routine successfully completed. 

LIB$_ERRROUCAL Success—error routine called. A file error was 

encountered but the error routine was called to 
handle the condition. 

LIB$_INVARG Invalid argument. Flags has one or more undefined 

bits set. 

LIB$_INVFILSPE Invalid file specification. Old-filespec, new- 

filespec, or default-filespec contains more than 
255 characters. 

LIB$_INVSTRDES Invalid string descriptor. One of the string argument 

descriptors was not a valid string descriptor. 
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LIB$_WRONUMARG Wrong number of arguments. An incorrect number 

of arguments was passed to LIB$RENAME_FILE. 

Any condition value returned by LIB$SCOPY_xxx; truncation errors are 
ignored. 

Any condition value returned by RMS. If the error-routine argument was 
not specified, this is the most severe of the RMS errors which occurred while 
renaming the files. 
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LIB$RESERVE_EF—Reserve Event Flag 



LIB$RESERVE_EF allocates a local event flag number specified by 

event-flag-num. 

FORMAT 

LIB$RESERVE_EF event-flag-num 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

event-flag-num 

VMS Usage: ef_number 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Event flag number to be allocated by LIB$RESERVE_EF. The event-flag-num 
argument contains the address of a signed longword integer that is this event 
flag number. 

DESCRIPTION 

LIB$RESERVE_EF allocates a particular local event flag number. It differs 
from LIB$GET__EF, which allocates an arbitrary event flag. 

Use LIB$FREE_EF to deallocate an event flag reserved with LIB$RESERVE_ 
EF. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_EF_ALRRES Event flag already reserved. 

LIB$_EF_RESSYS Event flag reserved to system. This occurs if the 

event flag number is outside the ranges of 1 to 23 


and 32 to 63. 
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EXAMPLE 


PROGRAM RESERVE_EF(INPUT. OUTPUT); 

PROCEDURE LIB$RESERVE_EF(7.REF EVENT.FLAG.NUM : INTEGER); EXTERN; 
PROCEDURE LIB$FREE_EF(7.REF EVENT.FLAG.NUM : INTEGER); EXTERN; 

VAR 

FLAG.NUM : INTEGER; 

BEGIN 

FLAG.NUM := 37; 

LIB$RESERVE_EF(FLAG_NUM); 

WRITELN(FLAG.NUM); 

LIBIFREE.EF(FLAG.NUM); 


END. 



The output generated by this PASCAL example program is as follows: 

37 
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LIB$RESET_VM_ZOI\IE—Reset Virtual 



Memory Zone 

LIB$RESET_VM_ZONE frees all blocks of memory that were 
previously allocated from the zone. 

FORMAT 

LIB$RESET_VM_ZONE zone-id 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

zone-id 

VMS Usage: long word-unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Zone identifier. The zone-id is the address of a longword that contains the 
identifier of a zone created by a previous call to LIB$CREATE_VML_ZONE or 
LIB$CREATE_USER_VM_ZONE. 

DESCRIPTION 

LIB$RESET_VM—ZONE frees all the blocks of memory that were previously 
allocated from the zone. The memory becomes available to satisfy 
further allocation requests for the zone; the memory is not returned to 
the processwide page pool managed by LIB$GET__VM__PAGE. Your program 
can continue to use the zone after you call LIB$RESET_VM_ZONE. 

Resetting a zone is a much more efficient way to reuse storage than 
individually freeing each allocated object in the zone. 

It is the caller's responsibility to ensure that he or she has "exclusive" 
access to the zone while the reset operation is being performed. Results are 
unpredictable if another thread of control attempts to perform any operation 
on the zone while RESET—VM—ZONE is in progress. 

If you specified deallocation filling when you created the zone, LIB$RESET_ 
VM—ZONE will fill all of the allocated blocks that are freed. 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Normal successful completion. 

LIB$_BADBLOADR An invalid zone-id argument. 
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LIB$REVERT—Revert to the Handler of the 

Procedure Activator 

LIB$REVERT deletes the condition handler established by 
LIB$ESTABLISH by clearing the address pointing to the condition 
handler from the activated procedure's stack frame. 

FORMAT 

LIB$REVERT 

RETURNS 

VMS Usage: address 
type: longword (unsigned) 

access: write only 

mechanism: by value 

Previous contents of SF$A_HANDLER (longword 0) of the caller's stack 
frame. This is the address of the condition handler previously in effect. If no 
condition handler was in effect, zero is returned. 

ARGUMENTS 

None. 

DESCRIPTION 

LIB$REVERT returns the address that it clears from the calling procedure's 
stack frame. LIB$REVERT is used only if your procedure is to establish and 
then cancel a condition handler for a portion of its execution. 

LIB$REVERT is provided primarily for use with languages without built-in 
error handling facilities, such as FORTRAN. Do not use LIB$REVERT from 
BASIC, COBOL, PASCAL, or PL/I. See the documentation for the language 
you are using for information about how that language handles errors. 

In MACRO, you merely use the following instruction rather than calling 
LIB$REVERT: 

CLRL (FP) ; set handler address to 0 

; in current stack frame 

CONDITION 

VALUES 

RETURNED 

None. 
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LIB$RUN_PROGRAM—Run New Program 

LIB$RUN_PROGRAM causes the current program to stop running 
and begins execution of another program. 

FORMAT 

LIB$RUN_PROGRAM pgm-name 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

pgm-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File name of the program to be run in place of the current program. The 
pgm-name argument contains the address of a descriptor pointing to this file 
name string. 

The maximum length of the file name is 255 characters. The default file type 
is .EXE. 


DESCRIPTION LIB$RUN_PROGRAM stops execution of the current program and begins 

execution of another program. 


• If successful, control does not return to the calling program. Instead, the 
$EXIT system service is called, the new program image replaces the old 
image in the user process, and the command interpreter gives control to 
the new image. 

• If unsuccessful, control returns to the command interpreter. 

This procedure is supported for use with the DCL and MCR CLIs. If an 
image is run directly as a subprocess or as a detached process, there is no CLI 
present to perform this function. In those cases, the error status LIB$_NOCLI 
is returned. 

LIB$RUN_PROGRAM causes the current image to exit at the point of the 
call and directs the Command Language Interpreter, if one is present, to start 
running another program. If LIB$RUN_PROGRAM executes successfully, 
control passes to the second program; if not, control passes to the Command 
Language Interpreter. The calling program cannot regain control. This 
technique is called chaining. 

This procedure is provided primarily for compatibility with PDP-11 systems, 
where chaining is used to extend the address space of a system. Because this 
procedure is provided for compatibility, it will not work unless your system 
has the optional compatibility mode. 
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This procedure may also be useful in a VAX/VMS environment where 
address space is severely limited and large images are not possible. For 
example, you might use chaining to perform system generation (SYSGEN) on 
a small virtual address space, because of a lack of disk space. 

With LIB$RUN_PROGRAM, the calling program can pass arguments to the 
next program in the chain only by using the common storage area. One way 
to do this is for the calling program to call LIB$PUT_COMMON to pass the 
information into the common storage area. Then the called program calls 
LIB$GET_COMMON to retrieve the data. 

In general, this practice is not recommended. There is no convenient way 
to specify the order and type of arguments passed into the common storage 
area; so programs that pass arguments in this way must know about the 
format of the data before it is passed. When you use common storage, it is 
very difficult to keep your program modular and AST-reentrant; a method of 
arbitration must be designated to define which program can modify common 
storage and when. 

Further, LIB$RUN_PROGRAM cannot be used if no Command Language 
Interpreter is present, as in the case of image subprocesses and detached 
subprocesses. 

If you want control to return to the caller, use LIB$SPAWN instead. 


CONDITION 

VALUES 

RETURNED 


LIB$_INVARG 

LIB$_NOCLI 


Invalid argument. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the function 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this 
error occurs while using the DCL or MCR CLIs, 
please report the problem to DIGITAL in a Software 
Performance Report (SPR). 


LIB$_UNECLIERR 


RTL-255 







Run-Time Library Routines 

LIB$SCANC 


LIB$SCAIMC—Scan for Characters, Return 

Relative Position 


LIB$SCANC is used to find a specified set of characters in the 
source string. LIB$SCANC makes the VAX SCANC instruction 
available as a callable procedure. 

FORMAT 

LIB$SCANC src-str , table-arr,mask 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


Relative position in the source string of the character that terminated the 
operation, or zero if the terminator character is not found. If the source string 
has a zero length, then a zero is returned. 


ARGUMENTS 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string used by LIB$SCANC to index into a table. The src-str argument 
contains the address of a descriptor pointing to this source string. 


table-arr 

VMS Usage: byte—unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Table that LIB$SCANC indexes into and ANDs with the mask byte. The 
table-arr argument contains the address of an unsigned byte array that is this 
table. 


mask 


VMS Usage: byte—unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Mask that is ANDed with bytes 
the address of an unsigned byte 


in table-arr. The mask argument contains 
that is this mask. 
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DESCRIPTION 

LIB$SCANC uses successive bytes of the string specified by src-str to index 
into a table. The byte selected from the table is ANDed with the mask byte. 
The operation is terminated when the result of the AND is equal to 1. 

CONDITION 

VALUES 

RETURNED 

None. 
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LIB$SCOPY_DXDX—Copy Source String 

Passed by Descriptor 
to Destination 


LIB$SCOPY_DXDX copies a source string passed by descriptor to a 
destination string. 

FORMAT 

LI B$SCOPY_DXDX src-str, dst-str 

corresponding 
jsb entry point 

LI B$SCOPY_DXDX6 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string to be copied to the destination string by LIB$SCOPY_DXDX. 
The src-str argument contains the address of a descriptor pointing to this 
source string. The descriptor class can be unspecified, fixed-length, decimal 
string, array, noncontiguous array, varying, or dynamic. 


dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string to which the source string is copied. The dst-str argument 
contains the address of a descriptor pointing to this destination string. 


The following actions occur depending on the class of the destination string's 
descriptor. 
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Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space-fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


DESCRIPTION LIB$SCOPY_DXDX returns all condition values as a status; truncation is a 

qualified success condition value (bit 0 set to 1). 

In addition, an equivalent JSB entry point is available, with RO containing the 
first argument and R1 containing the second. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_STRTRU 


LIB$_FATERRLIB 


LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. All characters 
in the input string were copied to the destination 
string. 

Procedure successfully completed. String 
truncated. The fixed-length destination string could 
not contain all of the characters copied from the 
source string. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$SCOPY_R_DX—Copy Source String 



Passed by Reference 
to Destination String 

LIB$SCOPY_R_DX copies a source string passed by reference to a 
destination string. 

FORMAT 

LI B$SCOPY_R_DX src-len ,src-adr,dst-str 

corresponding 
jsb entry point 

LI B$SCOPY_R_DX6 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

src-len 

VMS Usage: word—unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Length of the source string. The src-len argument contains the address of an 
unsigned word that is this length. 

src-adr 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by reference 

Source string to be copied to the destination string by LIB$SCOPY__R_.DX. 
The src-adr argument is the address of this source string. 

dst-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Destination string to which the source string is copied. The dst-str argument 
contains the address of a descriptor pointing to this destination string. 

The following actions occur depending on the class of the destination string's 
descriptor. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


Class Field 

Action 

DSC$K_CLASS_S,Z,SD,A,NCA 

Copy the source string. If needed, space fill 
or truncate on the right. 

DSC$K_CLASS_D 

If the area specified by the destination 
descriptor is large enough to contain the 
source string, copy the source string and set 
the new length in the destination descriptor. 

If the area specified is not large enough, 
return the previous space allocation (if any) 
and then dynamically allocate the amount 
of space needed. Copy the source string 
and set the new length and address in the 
destination descriptor. 

DSC$K_CLASS_VS 

Copy source string to destination string up 
to the limit of DSC$W_MAXSTRLEN with 
no padding. Readjust current length field to 
actual number of bytes copied. 


LIB$SCOPY_JR_DX returns all condition values as a status; truncation is a 
qualified success condition value (bit 0 set to 1). 

In addition, an equivalent JSB entry is available, with RO being the first 
argument, R1 the second, and R2 the third. The length argument is passed in 
bits 15:0 of RO. 


SS$_NORMAL 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. All characters 
in the input string were copied to the destination 
string. 

Procedure successfully completed. String 
truncated. The fixed-length destination string could 
not contain all of the characters copied from the 
source string. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$SET_LOGICAL—Set Logical Name 

LIB$SET_LOGICAL requests the calling process’s Command 
Language Interpreter (CLI) to define or redefine a supervisor-mode 
process logical name. It provides the same function as the DCL 
DEFINE command. 


FORMAT LIB$SET_LOGICAL log-nam[,value][,table-desc] 

[,attributes] [, item-list] 

Either the item-list or value argument must be specified. If both item-list 
and value are specified, the value argument is ignored. 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


log-nam 

VMS Usage: 
type: 
access: 
mechanism: 


logical_name 
character string 
read only 
by descriptor 

Logical name to be defined or redefined. The log-nam argument contains the 
address of a descriptor pointing to this logical name string. The maximum 
length of a logical name is 255 characters. 

value 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Value to be given to the logical name. The value argument contains the 
address of a descriptor pointing to this value string. The maximum length of 
a logical name value is 255 characters. 

If omitted, an item list must be present to specify the value(s) of the logical 
name. 


table-desc 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the table in which to create the logical name. The table-desc 
argument contains the address of a descriptor pointing to the logical name 
table. If no table is specified, LNM$PROCESS is used as the default. 
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attributes 


VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Logical name or translation attributes. The attributes argument is the address 
of an unsigned longword which contains the logical name or translation 
attributes. 


LNM$M_CONFINE and LNM$M_NO_ALIAS are currently available logical 
name attributes. See the description of the $CRELNM system service in 
the VAX/VMS System Services Reference Manual for definitions of LNM$M_ 
CONFINE and LNM$M_NO_ALIAS. If omitted, no special logical name 
attribute is established. 


If no item-list is specified, the translation attributes LNM$M_CONCEALED 
and LNM$M_TERMINAL may be specified. See the description of the 
ASSIGN command in the VAX/VMS DCL Dictionary for definitions of these 
attributes. If an item-list is specified, it will contain the translation attributes 
for each equivalence string in the attribute. 


item-list 

VMS Usage: item_Jist 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Item list describing the equivalence names for this logical name. The item- 
list argument contains the address of an unsigned longword array that 
contains this item list. If item-list is not specified, the logical name will have 
only one value, as specified in the value argument. 


Either value or item-list must be specified. If neither is specified, the LIB$_ 
INVARG error is produced. If both value and item-list are specified, the 
value argument is ignored. 


If item-list is specified, only logical name attributes are permitted. 
Translation attributes appear in the item list. 


Item-list is only needed when you wish to create multiple equivalence strings 
for a single logical name. 


DESCRIPTION If the optional table-desc argument is defined, the logical name will be placed 

in the table specified by the table-desc argument; otherwise, the logical name 
is placed in the LNM$PROCESS table. 

Unlike the system services $CRELOG and $CRELNM, LIB$SET_LOGICAL 
does not require the caller to be executing in supervisor mode to define 
a supervisor-mode logical name. Supervisor-mode logical names are not 
deleted when an image exits. A program can obtain the current value of any 
logical name by calling the system service $TRNLNM. For more information 
on logical names see the VAX/VMS System Services Reference Manual. 

This procedure is supported for use with the DCL and MCR Command 
Language Interpreters. If an image is run directly as a subprocess or as a 
detached process, there is no CLI present to perform this function. In that 
case, the error status LIB$_NOCLI is returned. 


See the VAX/VMS DCL Dictionary for a description of the DCL DEFINE 
command. 
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CONDITION SS$_NORMAL 

VALUES SS$_SUPERSEDE 

RETURNED 

SS$_BUFFEROVF 

SS$_ACCVIO 

SS$_BADPARAM 

SS$_INSFMEM 

SS$_IVLOGNAM 

SS$_IVLOGTAB 

SS$_NOPRIV 

SS$_TOOMANYLNAM 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_NOCLI 


LIB$_UNECLIERR 


Procedure successfully completed. 

Procedure successfully completed; the previous 
definition of the logical name was replaced. 

Procedure successfully completed; however, a 
buffer overflow occurred. 

Access violation. The logical name or its value 
could not be read. 

Bad argument. 

Insufficient dynamic memory. 

Invalid logical name. The logical name or its value 
contained more than 255 characters. 

Invalid logical name table. 

No privileges for attempted operation. 

Logical name translation exceeded allowed depth. 

Neither the value nor the item-list argument was 
specified. 

Invalid string descriptor. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the function 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL Command Language 
Interpreter, please report the problem to DIGITAL 
in a Software Performance Report (SPR). 


EXAMPLE 

0I1I2I3I4I6I6I7I 
12346678901234667890123456789012345678901234567890123450789012346678901234667890 
C* Initialize name lor logical 
C MOVE 'RPG.LOG' LOGICL 7 

C* Initialize value to which logical is to be set 
C MOVE 'OFF' SETVAL 3 

C SETLOG EXTRN'LIB$SET_LOGICAL' 

C* Call RTL routine to set the logical 
C CALL SETLOG 

C PARMD LOGICL 

C PARMD SETVAL 

C SETON LR 


The RPG II program above sets the logical RPG—LOG to OFF. This value can 
be displayed after the program is run with SHOW LOGICAL as follows: 

$ SHOW LOGICAL RPG_L0G 

"RPG.LOG" * "OFF" (LNM$PROCESS.TABLE) 
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LIB$SET_SYMBOL—Set Value of CLI 

Symbol 

LIB$SET_SYMBOL requests the calling process's Command 
Language Interpreter (CLI) to define or redefine a CLI symbol. 


FORMAT 

LIB$SET_SYMBOL symbol,value [, tbl-ind] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

symbol 

VMS Usage: char—string 
type: character string 

access: read only 

mechanism: by descriptor 

Name of the symbol to be defined or modified by LIB$SET—SYMBOL. The 
symbol argument is the address of a descriptor pointing to this symbol string. 
If you redefine a previously defined CLI symbol, the symbol value is modified 
to the new value that you provide. 


The symbol name is converted to uppercase and trailing blanks are removed 
before use. You must begin a symbol name with a letter (A through Z), an 
underscore (_), or a dollar sign ($). The maximum length of symbol is 255 
characters. 


value 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Value to be given to the symbol. The value argument is the address of a 
descriptor pointing to this value string. 


Trailing blanks are not removed from the value string before use. The 
maximum length of value is 255 characters. Integer values are not allowed; 
LIB$SET_SYMBOL is intended to access string CLI symbols, not integer CLI 
symbols. 


tbl-ind 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Indicator of the table which will contain the defined symbol. The tbl-ind 
argument is the address of a signed longword integer that is this table 
indicator. 
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If omitted, the local symbol table is used. The following are possible values 

for tbl-ind. 


Symbolic Name 

Value 

Table Used 

LIB$K_CLI_LOCAI_SYM 

1 

Local symbol table 

LIB$K_CLI_GLOBAI_SYM 

2 

Global symbol table 


DESCRIPTION CLI symbols created using LIB$SET-SYMBOL may be inaccessible by other 

CLI commands. To avoid this situation, make sure that your symbol names 
are alphanumeric and that the first character is alphabetic. 

LIB$K_CLL_LOCAl^SYM and LIB$K_CLL_GLOBAL—SYM are defined as 
global symbols and in DIGITAL-supplied symbol libraries (macro or module 
name $LIBCLIDEF). 

This procedure is supported for use with the DCL Command Language 
Interpreter. If used with the MCR CLI, the error status LIB$_NOCLI will be 
returned. If an image is run directly as a subprocess or as a detached process, 
there is no CLI present to perform this function. In this case, the error status 
LIB$—NOCLI is returned. 


CONDITION SS$_NORMAL 

VALUES LIB$_AMBSYMDEF 

RETURNED 

LIB$_FATERRLIB 

LIB$_INSCLIMEM 

LIB$_INSVIRMEM 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_INVSYMNAM 


Procedure successfully completed. 

Ambiguous symbol definition. The symbol name 
you want to define is ambiguous when compared 
with existing symbol names. This condition might 
arise if abbreviated symbols have been defined 
previously. See the VAX/VMS DCL Dictionary for 
more information on abbreviated symbols. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient CLI memory. The CLI could not get 
enough virtual memory to assign another symbol. 
This condition may be caused by having too many 
symbols defined; deleting some symbol definitions 
may make enough room for the new symbol. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 

Invalid argument. The value of tbl-ind was invalid 
or the length of value was greater than 255 
characters. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 

Invalid symbol name. The length of symbol was 
greater than 255 characters or symbol did not 
begin with a letter. 
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LIB$_NOCLI 


LIB$_UNECLIERR 


No CLI present to perform function. The calling 
process did not have a CLI to perform the function 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 

Unexpected CLI error. The CLI returned an error 
status which was not recognized. This error may 
be caused by use of a nonstandard CLI. If this error 
occurs while using the DCL Command Language 
Interpreter, please report the problem to DIGITAL 
in a Software Performance Report (SPR). 


EXAMPLE 


0I1)2I3|4|6I6|7I 

12346678901234567890123456789012345678901234567890123456789012345678901234667890 


C* Initialize name 1 or symbol 
C MOVE 'RPG.SYM' SYMBOL 7 

C* Initialize value to which symbol is to be set 
C MOVE 'ON' SETVAL 2 

C SETSYM EXTRN'LIB$SET_SYMBOL' 

C* Call RTL routine to set the symbol 
CALL SETSYM 
PARMD SYMBOL 

PARMD SETVAL 

SETON LR 

The RPG II program above sets the symbol RPG_SYM to ON. This value can 
be displayed after the program is run with SHOW SYMBOL as follows: 



$ SHOW SYMBOL RPG.SYM 
RPG.SYM = "ON" 
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LIB$SFREE1_DD—Free One Dynamic 



String 

LIB$SFREE1_DD returns one dynamic string area to free storage. 

FORMAT 

LIB$SFREE1 _DD dsc-adr 

corresponding 
jsb entry point 

LIB$SFREE1 _DD6 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

dsc-adr 

VMS Usage: quadword_unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference 

Dynamic descriptor specifying the area to be deallocated. The dsc-adr 
argument is the address of an unsigned quadword that is this descriptor. The 
descriptor is assumed to be dynamic and its class field is not checked. 


DESCRIPTION Before a procedure deallocates a dynamic descriptor, it must use 

LIB$SFREE1_DD or LIB$SFREEn_DD to deallocate the string storage 



space specified by the dynamic descriptor. Otherwise, string storage is not 
deallocated and your program can run out of memory. 

This procedure deallocates the described string space and flags the descriptor 
as describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH 
= 0). 

CONDITION 

VALUES 

RETURNED 

SS$_NORMAL Procedure successfully completed. 

LIB$_FATERRLIB Fatal internal error. 
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LIB$SFREEN_DD—Free One or More 

Dynamic Strings 


LIB$SFREEN_DD returns one or more dynamic strings to free 
storage. 

FORMAT 

LIB$SFREEN_DD dsc-num ,first-dsc 

corresponding 
jsb entry point 

LIB$SFREEN_DD6 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

dsc-num 

VMS Usage: longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Number of adjacent descriptors to be flagged by LIB$FREEN_DD as having 
no allocated area (DSC$ A-POINTER = 0 and DSC$W_LENGTH = 0). The 
dsc-num argument contains the address of an unsigned longword that is this 
number. The deallocated area is returned to free storage. 


first-dsc 

VMS Usage: vector_quadword_unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference, array reference 

First descriptor of an array of descriptors. The first-dsc argument contains the 
address of an unsigned quadword that is this first descriptor. The descriptors 
are assumed to be dynamic, and their class fields are not checked. 

DESCRIPTION 

Before a procedure that allocates space returns to its caller, it must use 
LIB$SFREE1_DD or LIB$SFREEN_DD to deallocate the string storage space 
specified by any descriptors located in the stack. Otherwise, space is not 
deallocated and your program might run out of virtual memory. 

This procedure deallocates the described string space and flags each descriptor 
as describing no string at all (DSC$A_POINTER = 0 and DSC$W_LENGTH 
= 0). 
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CONDITION SSS—NORMAL 

VALUES LIB$_FATERRLIB 

RETURNED 


Procedure successfully completed. 
Fatal internal error. 
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UB$SGET1_DD—Get One Dynamic String 



LIB$SGET1_DD allocates dynamic virtual memory to the string 
descriptor you specify. 

FORMAT 

LIB$SGET1 _DD length ,string 

corresponding 
jsb entry point 

LIB$SGET1_DD_R6 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

length 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Number of bytes of dynamic virtual memory to be allocated by LIB$SGET1_ 
DD. The length argument is the address of an unsigned word that 
contains this number. The amount of storage allocated may be rounded 
up automatically. If the number of bytes is zero, a small amount of space is 
allocated. 

string 

VMS Usage: quadword_unsigned 
type: quadword (unsigned) 

access: modify 

mechanism: by reference 

Descriptor of the dynamic string to which LIB$SGET1_DD will allocate the 
dynamic virtual memory. The string argument contains the address of an 
unsigned quadword that is this descriptor. 

The string argument must contain the address of a dynamic string descriptor; 
LIB$GET1_DD returns an unpredictable result if any other type of descriptor 
is specified by this argument. 

The class field is not checked but is set to dynamic (DSC$B_CLASS = 2). 

The length field (DSC$W_LENGTH) is set to length, and the address field 
(DSC$A__POINTER) points to the string area allocated. 

DESCRIPTION 

LIB$GET1_DD is similar to LIB$SCOPY_DXDX except that no source string 
is copied. You can write anything you want in the allocated area. 

If string already has dynamic memory allocated to it, but the amount 
allocated is less than length, that space is deallocated before LIB$SGET1_DD 
allocates new space. 
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CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

LIB$_FATERRLIB 


LIB$_INSVIRMEM 


Procedure successfully completed. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 
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LIB$SHOW_TIMER—Show Accumulated 

Times and Counts 



LIB$SHOW_TIMER returns times and counts accumulated since the 
last call to LIB$INIT_TIMER and displays them on SYS$OUTPUT. A 
user-supplied action routine may change this default behavior. 

FORMAT 

LIB$SHOW_TIMER [handle-adr][,code][,action-rtn 

[,user-arg]] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

handle-adr 

VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Block of storage containing the value returned by a previous call to LIB$INIT_ 
TIMER. The handle-adr argument is the address of an unsigned longword 
integer containing that value. 

• If specified, the pointer must be the same value returned by a previous 
call to LIB$INIT_TIMER. 

• If omitted, LIB$SHOW-TIMER will use a block of memory allocated by 
LIB$INIT_TIMER. 

• If handle-adr is omitted and LIB$INIT_TIMER has not been called 
previously, the error LIB$_INVARG is returned. LIB$INIT_TIMER must 
be called prior to a call to LIB$SHOW_TIMER. 

LIB$SHOW_TIMER assumes that LIB$INIT_TIMER has been previously 
called, and that the results of that call are stored either in a block pointed to 
by handle-adr, or in the memory allocated by LIB$INIT_TIMER. 

code 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Integer specifying the statistic you want; if it is omitted or zero, all five 
statistics are returned on one line. The code argument is the address of a 
signed longword integer containing the statistic code. 
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The following values are allowed for the code argument. 


Value 

Description 

1 

Elapsed time 

2 

CPU time 

3 

Buffered I/O 

4 

Direct I/O 

5 

Page faults 


action-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied action routine called by LIB$SHOW_TIMER. The action-rtn 
argument is the address of the entry mask to this routine. The default action 
of LIB$SHOW_TIMER is to write the results to SYS$OUTPUT. An action 
routine is useful if you want to write the results to a file, or in general, 
anywhere other than SYS$OUTPUT. 


The action routine returns either a success or failure condition value; this 
status is returned to the calling program as the value of LIB$SHOW_TIMER. 


user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: by value 

A 32-bit value to be passed to the action routine without interpretation, 
omitted, LIB$SHOW_TIMER passes a zero by value to the user routine. 


If 


DESCRIPTION LIB$SHOW_TIMER returns the times and counts accumulated since the last 

call to LIB$INIT_TIMER. By default, when neither code nor action-rtn is 
specified in the call, LIB$SHOW_TIMER writes to SYS$OUTPUT a line giving 
the information listed below. 


Shown on Line 

Description 

ELAPSED = hhhh:mm:ss.cc 

Elapsed real time 

CPU = hhhh:mm:ss.cc 

Elapsed CPU time 

BUFIO = nnnn 

Count of buffered I/O operations 

DIRIO = nnnn 

Count of direct I/O operations 

PAGEFAULTS = nnnn 

Count of page faults 


Any one or all five statistics can be written to SYS$OUTPUT or passed to 
your user-supplied action routine for other processing. 
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Call Format for an Action Routine 

Action routine is a user-supplied routine called by LIB$SHOW_TIMER. The 
action routine is used when you wish to write results to anywhere other 
than SYS$OUTPUT. The action routine is called only when you specify the 
action-rtn argument in the call to LIB$SHOW-TIMER. 

LIB$SHOW_TIMER calls the action routine using this format: 


action-rtn out-str [,user-arg] 

out-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Fixed-length string containing the statistics requested. The string is formatted 
exactly as it would be if written to SYS$OUTPUT. The leading character is 
blank. 


user-arg 


VMS Usage: 
type: 
access: 
mechanism: 


user_arg 
unspecified 
read only 
by value 


A 32-bit value passed to LIB$SHOW_TIMER. The user argument is passed 
without interpretation to the action routine. 


CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. Either code or handle-adr was 

invalid. 

Any condition values returned by LIB$PUT_OUTPUT or your action routine. 


EXAMPLE 


PROGRAM SHOW.TIMER(INPUT,OUTPUT); 

<♦> 

{ This PASCAL example demonstrates how to use LIB$SHOW_TIMER. 
{-> 


VAR 

RETURNED.STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$INIT_TIMER( 

HANDLE.ADR : [REFERENCE] UNSIGNED := 7.IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$SHOW_TIMER( 

HANDLE.ADR : [REFERENCE] UNSIGNED := 7.IMMED 0; 

CODE : INTEGER; 

[IMMEDIATE,UNBOUND] 

PROCEDURE ACTION.RTNC OUT.STR : [CLASS.S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
USER.ARG : INTEGER) := 7.IMMED 0; 

USER.ARG : INTEGER := 7.IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$ST0P( 

CONDITION_STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 

FAO.ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 
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PROCEDURE USER.ACTION.RTN( 

OUT.STR : [CLASS.S] PACKED ARRAY [L..U:INTEGER] OF CHAR; 
USER.ARG : INTEGER); 

BEGIN 

WRITELN('User argument is •,USER.ARG:1); 

WRITELN(0UT_STR); 

END; 

BEGIN 

<+> 

{ Call LIB$INIT_TIMER to initialize RTL internal counters. 

{-> 

RETURNED.STATUS := LIB$INIT_TIMER; 

IF NOT ODD(RETURNED_STATUS) 

THEN 

LIB$ST0P(RETURNED_STATUS); 

{♦> 

{ Print a line of text to waste time. 

{-> 

WRITELN('Spend time to acquire elapsed real time and page faults'); 

{+> 

{ Call LIB$SHOW_TIMER to display counters. 

{-> 

RETURNED.STATUS := LIB$SHOW_TIMER(,0,USER.ACTION.RTN,5); 

END. 


This PASCAL program demonstrates how to call LIB$SHOW_TIMER. The 
output generated by this PASCAL example is as follows: 

$ RUN SHOW.TIMER 

Spend time to acquire elapsed real time and page faults 
User argument is 5 

ELAPSED: 00:00:00.66 CPU: 0:00:00.13 BUFIO: 2 DIRIO: 7 FAULTS: 17 
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LIB$SHOW_VM—Show Virtual Memory 

Statistics 

LIB$SHOW_VM returns the statistics accumulated from calls to 
LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_ 
VM_PAGE. 

FORMAT 

LI B$SHOW_VM [code] [,action-rtn [, user-arg]] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

code 

VMS Usage: longword—signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Code specifying any one of the statistics to be written to SYS$OUTPUT or 
passed to an action routine for processing. The code argument is the address 
of a signed longword integer containing the statistic code. This is an optional 
argument. If the statistic code is omitted or is zero, statistics for values 1, 2, 
and 3 are returned on one line. 

The following values are allowed for the code argument. 


Value Statistic 

0 Statistics for values 1, 2, and 3 are returned 

1 Number of successful calls to LIB$GET_VM 

2 Number of successful calls to LIB$FREE_VM 

3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by 

LIB$FREE_VM 

4 Statistics for values 5, 6, and 7 are returned 

5 Number of calls to LIB$GET_VM_PAGE 

6 Number of calls to LIB$FREE_VM_PAGE 

7 Number of pages allocated by LIB$GET_VM_PAGE but not yet 
deallocated by LIB$FREE_VM_PAGE 


action-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied action routine called by LIB$SHOW_VM. By default, 
LIB$SHOW_VM returns statistics to SYS$OUTPUT. An action routine is 
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useful when you want to return statistics to a file or, in general, to anyplace 
other than SYS$OUTPUT. The action-rtn argument is the address of the 
entry mask to the action routine. The routine returns either a success or 
failure condition value, which will be returned as the value of LIB$SHOW_ 
VM. 

For more information on the action routine, see "Call Format for an Action 
Routine" in the Description section. 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

A 32-bit value to be passed directly to the action routine without 
interpretation. That is, the contents of the argument list entry user-arg 
are copied to the argument list entry for action-rtn. 

DESCRIPTION 

LIB$SHOW_VM returns the statistics accumulated from calls to LIB$GET_ 
VM/LIB$FREE_VM and LIB$GET_VM_PAGE/LIB$FREE_VM_PAGE. By 
default, with neither code nor action-rtn specified in the call, LIB$SHOW_ 
VM writes a line giving the following information to SYS$OUTPUT: 

mmm calls to LIB$GET_VM, nnn calls to LIB$FREE_VM, ppp bytes still allocated 

Optionally, any one of six statistics can be output to SYS$OUTPUT and/or 
the line of information can be passed to a user-specified "action routine", for 
processing different from the default. 

Call Format for an Action Routine 

The action routine is a user-supplied routine that LIB$SHOW_VM calls if you 
specify the action-rtn argument in the call to LIB$SHOW_VM. 

The call format for an action routine is: 

action-rtn out-str ,user-arg 

out-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Statistics supplied by LIB$SHOW_VM. The out-str argument is the address 
of a descriptor pointing to an address into which LIB$SHOW_VM writes 
the statistics. The string is formatted exactly as it would be if written to 
SYS$OUTPUT. The first character is a blank; carriage-retum/line-feed 
combinations are not included. 

user-arg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: by value 

The 32-bit value passed to LIB$SFiOW_VM is passed to the action routine 
without interpretation. If the user-arg argument is omitted in the call to 
LIB$SHOW_VM, a zero is passed by value to the user routine. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL Procedure successfully completed. 

LIB$_INVARG Invalid arguments. This can be caused by an invalid 

value for code. 

Any condition values returned by LIB$PUT_OUTPUT or your action routine. 
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LIB$SIGNAL—Signal Exception Condition 



LIB$SIGNAL generates a signal that indicates that an exception 
condition has occurred in your program. If a condition handler does 
not take corrective action and the condition is severe, then your 
program will exit. 

FORMAT 

LIB$SIGNAL condition-value 1 [,number 1 ] 

[, FA O-arg 1...,FA O-argn 1 ] 

[, condition-value2] [, number2] 

[, FA O-arg2. ..,FA O-argn 2] 

Only the condition-valuel argument must be specified; other arguments are 
optional. The numberl argument, if specified, contains the number of FAO 
arguments that will be associated with condition-valuel. The condition- 
value2 argument is optional; it may be specified with or without the number2 
or FAO-arg2 arguments. The number2 argument, if specified, contains the 
number of FAO arguments that will be associated with condition-value2. 

You may specify condition-value3, condition-value4, condition-values, and 
so on, along with their corresponding number and FAO arguments. 

RETURNS 

None. 

ARGUMENTS 

condition-value 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by value 

VAX 32-bit condition value. The condition-value argument is an unsigned 
longword that contains this condition value. 

Section 7.1.2 explains the format of a VAX condition value. 

number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of FAO arguments associated with the condition value. The number 
argument is a signed longword integer that contains this number. If omitted 
or specified as zero, no FAO arguments follow. 
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FAO-arg(s) 

VMS Usage: varying-arg 
type: unspecified 

access: read only 

mechanism: unspecified 

Additional FAO (formatted ASCII output) argument(s) which are associated 
with the specified condition value. 

Section 7.1.5 explains the message format. 

DESCRIPTION 

Your program calls LIB$SIGNAL whenever it needs to indicate an exception 
condition or output a message rather than return a status code to its calling 
program. 

LIB$SIGNAL examines the primary and secondary exception vectors and then 
scans the stack, frame by frame, starting at the top of the stack, and calls 
each condition handler it finds. LIB$SIGNAL locates stack frames by using 
each frame's saved frame pointer (FP) to chain back through the stack frames. 
Section 7.1.3 provides additional information on this process. 

If one of the handlers that LIB$SIGNAL calls returns a continue code (that is, 
any success completion code with bit 0 set to 1), LIB$SIGNAL returns to its 
caller, which should be prepared to continue execution. 

If the handler that LIB$SIGNAL calls returns a resignal code (that is, any 
completion code with bit 0 set to 0) LIB$SIGNAL continues to scan the stack. 

If the handler called by LIB$SIGNAL calls SYS$UNWIND, control will not 
return to LIB$SIGNAL's caller, thus changing the program flow. A handler 
can also modify the saved copy of R0/R1 in the mechanism vector, changing 
registers R0 and R1 after the stack has been unwound. If a handler does 
neither of these things, then all registers including R0/R1 and the hardware 
condition codes are preserved. 

LIB$SIGNAL will, if necessary, scan up to 65,536 previous stack frames and 
then finally examine the last-chance exception vector. 

The LIB$SIGNAL argument list, the Program Counter (PC) and Processor 
Status Longword (PSL) of the caller are appended to build the signal 
argument vector. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLES 


C This FORTRAN example program demonstrates the use of 
C LIBISIGNAL. 

C 

C This program defines SS$... signals and thenc alls LIB$SIGNAL 
C passing the access violation code as the argument. 

C- 

INCLUDE '($SSDEF)' 

CALL LIBISIGNAL ( XVAL(SS$_ACCVIO) ) 

END 


In FORTRAN, this code fragment signals the standard system message 
ACCESS VIOLATION. 


The output generated by this FORTRAN program is as follows: 


XSYSTEM-F-ACCVIO, access violation, reason mask=10, virtual address=03C00020, PC=OOOOOOOO t PSL=08000000 
XTRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 

D2$MAIN D2IMAIN 683 00000010 00000410 

B 

; + 

; This MACRO example program demosntrates the use of LIB$SIGNAL 
; by forcing an access violation to be signaled. 


.EXTRN SS$_ACCVI0 ; Declare external symbol 
.ENTRY START,0 

PUSHL #SS$_ACCVI0 ; Condition value symbol 
; for access violation 

CALLS *1, G~LIB$SIGNAL ; Signal the condition 
RET 

.END START 


.EXTRN SSI.ACCVIO 

PUSHL #SS$_ACCVI0 

CALLS #1. LIB$SIGNAL 


Declare external symbol 
Condition value symbol 
for access violation 
Signal the condition 


This example shows the equivalent MACRO code. The output generated by 
this program is as follows: 

XSYSTEM-F-ACCVIO, access violation, reason mask=0F, virtual address=03C00000, PC=00000000, PSL=00000000 
XTRACE-F-TRACEBACK, symbolic stack dump follows 

module name routine name line rel PC abs PC 

.MAIN. START 0000000F 0000020F 
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LIB$SIG—TO—RET—Signal Converted to a 



Return Status 

LIB$SIG_TO_RET converts any signaled condition value to a value 
returned as a function. This value is returned to the caller of the 
user procedure containing LIB$SIG_TO_RET. This routine may be 
established as or called from a condition handler. 

FORMAT 

LIB$SIG_TO_RET sig-args ,mch-args 

RETURNS 

VMS Usage: cond_value 

type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

sig-args 

VMS Usage: vector_Jongword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Signal argument vector. The sig-args argument contains the address of an 
array of unsigned longwords that is this signal argument vector stack. 

See Section 7.1.3.1 for a description of the signal argument vector. 

mch-args 

VMS Usage: vector_longword__unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Mechanism arguments vector. The mch-args argument contains the address 
of an array of unsigned longwords that is this mechanism arguments vector 
stack. 

See Section 7.1.3.2 for a description of the mechanism argument vector. 

DESCRIPTION 

LIB$SIG_TO_RET is called with the argument list that was passed to a 
condition handler by the VAX Condition Handling Facility. The signaled 
condition is converted to a value returned to the program that called the 
procedure that established the handler. The stack is unwound to the caller 
of the establisher of the condition handler. The condition code is returned as 
the value in RO. See Section 7 for more information on condition handling. 

LIB$SIG_TO_RET causes the stack to be unwound to the caller of the 
procedure that established the handler which was called by the signal. 
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CONDITION SS$_NORMAL 

VALUE 

RETURNED 


EXAMPLE 


Procedure successfully completed; SS$_UNWIND 
completed. Otherwise, the error code from SS$_ 
UNWIND is returned. 


C+ 

C This FORTRAN example demonstrates how to use LIB$SIG_TO_RET. 

C 

C This function subroutine inverts each entry in an array. That is, 

C a(i,j) becomes l/a(i,j). The subroutine has been declared as an integer 
C function so that the status of the inversion may be returned. The status 
C should be success, unless one of the a(i,j) entries is zero. If one of 
C the a(i,j) ■ 0, then l/a(i,j) is division by zero. This division by zero 
C does not cause a division by zero error, rather, the routine will return 
C signal a failure. 

C- 

INTEGER*4 FUNCTION FLIP(A,N) 

DIMENSION A(N,N) 

EXTERNAL LIB$SIG_TO_RET 

CALL LIB$ESTABLISH (LIB$SIG_TO_RET) 

FLIP = .TRUE. 

C+ 

C Flip each entry. 

C- 

DO 1 I = 1. N 
DO 1 J = 1. N 

1 A(I.J) = 1.0/A(I,J) 

RETURN 

END 


C+ 

C This is the main code. 

C- 

INTEGER STATUS. FLIP 

REAL ARRAY,1(2,2),ARRAY.2(3,3) 

DATA ARRAY,1/1,2,3,4/,ARRAY_2/1,2,3,5,0,5,6,7,2/ 
CHARACTERS32 TEXT(2).STRING 

DATA TEXT(1)/' This array could be flipped. '/. 
1 TEXT(2)/' This array could not be flipped.'/ 

STRING = TEXT(1) 

STATUS = FLIP(ARRAY,1,2) 

IF ( .NOT. STATUS) STRING * TEXT(2) 

TYPE '(a)•, STRING 

STRING = TEXT(1) 

STATUS = FLIP(ARRAY.2,3) 

IF ( .NOT. STATUS) STRING = TEXT(2) 

TYPE '(a)•. STRING 

END 


This FORTRAN example program inverts each entry in an array. The output 
generated by this program is as follows: 


This array could be flipped. 
This array could not be flipped 
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LIB$SIG_TO—STOP—Convert a Signaled 

Condition to a 



Signaled Stop 

LIB$SIG_TO_STOP converts a signaled condition to a signaled 
condition that cannot be continued. 

FORMAT 

LIB$SIG_TO_STOP sig-args ,mch-args 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

sig-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference, array reference 

Signal argument vector. The sig-args argument contains the address of an 
array of unsigned longwords that is this signal argument vector stack. 

See Section 7.1.3.1 for a description of the signal argument vector. 

mch-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Mechanism argument vector. The mch-args argument contains the address of 
an array of longwords that is this mechanism argument vector stack. 

See Section 7.1.3.2 for a description of the mechanism argument vector. 

DESCRIPTION 

LIB$SIG_TO_STOP causes a signal to appear as though it had been signaled 
by a call to LIB$STOP. When a signal is generated by LIB$STOP, the severity 
code is forced to SEVERE and control cannot return to the procedure that 
signaled the condition. LIB$SIG_TO—STOP may be enabled as a condition 
handler for a procedure or it may be called from a condition handler. 

If the condition value in sig-args is SS$_UNWIND, then LIB$SIG_TO_STOP 
returns the error condition LIB$_INVARG. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

LIB$_INVARG 


Procedure successfully completed; SS$_UNWIND 
completed. Otherwise, the error code from SS$_ 
UNWIND is returned. 

Invalid argument. The condition code in sig-args is 
SS$_UNWIND. 
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LIB$SIM_TRAP—Simulate Floating Trap 



LIB$SIM_TRAP converts floating faults to floating traps. It can be 
enabled as a condition handler or can be called by one. 

FORMAT 

LIB$SIM_TRAP sig-args,mch-args 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

sig-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: modify 

mechanism: by reference, array reference 

Signal argument vector. The sig-args argument contains the address of an 
array of longwords that is this signal argument vector stack. 

See Section 7.1.3.1 for a description of the signal argument vector. 

mch-args 

VMS Usage: vector_longword_unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Mechanism argument vector. The mch-args argument contains the address of 
an array of longwords that is this mechanism argument vector stack. 

See Section 7.1.3.2 for a description of the mechanism argument vector. 

DESCRIPTION 

LIB$SIM_TRAP converts floating faults to floating traps. It can be enabled as 
a condition handler or can be called by one. 

LIB$SIM_TRAP intercepts floating overflow, underflow, and divide-by-zero 
faults. It simulates the instruction causing the condition up to the point where 
a fault should be signaled, then signals the corresponding floating trap. 

Since LIB$SIM_TRAP nullifies the condition handling for the original fault 
condition, the final condition signaled by the routine will be from the context 
of the instruction itself, rather than from the condition handler. The signaling 
path is identical to that of a hardware-generated trap. The signal argument 
vector is placed so the last entry in the vector will be the user's stack pointer 
at the completion of the instruction (for a trap), or at the beginning of the 
instruction (for a fault). 

See the VAX-11 Architecture Reference Manual for more information on faults 
and traps. 
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CONDITION SS$_RESIGNAL 

VALUE 

RETURNED 


Resignal condition to next handler. The exception 
was not one that LIB$SIM_TRAP could handle. 
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LIB$SKPC—Skip Equal Characters 

LIB$SKPC compares each character of a given string with a given 



character and returns the relative position of the first nonequal 
character as an index. LIB$SKPC makes the VAX SKPC instruction 
available as a callable procedure. 

FORMAT 

LIB$SKPC char-str,src-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The relative position in the source string of the first unequal character. 
LIB$SKPC returns a zero if the source string was of zero length or if every 
character in src-str was equal to char-str. 

ARGUMENTS 

char-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String whose initial character is to be used by LIB$SKPC in the comparison. 
The char-str argument contains the address of a descriptor pointing to this 
string. Only the first character of char-str is used, and the length of char-str 
is not checked. 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

String to be searched by LIB$SKPC. The src-str argument contains the 
address of a descriptor pointing to this string. 


DESCRIPTION LIB$SKPC compares the initial character of char-str with successive 

characters of src-str until it finds an inequality or reaches the end of the 



src-str. It returns the relative position of this unequal character as an index, 
which is the relative position of the first occurrence of a substring in the 
source string. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


C+ 

C This FORTRAN example program illustrates the use of LIB$SKPC. 

C LIBlSKPC makes the VAX SKPC instruction avaiable as a callable procedure. 

C LIB$SKPC compares each character of a given string with a given character. 

C It returns the relative position of the first nonequal character as an index. 
C- 

I = LIBlSKPC (' ', ' ABC') 

TYPE 1, I 

1 FORMAT(' The blank character matches the',I2,'nd character in') 

TYPE *,'the string " ABC"' 

J = LIBISKPC ('A', 'AAA') 

TYPE 2, J 

2 FORMAT(' The character "A" matches the',I2,'th character in') 

TYPE *,'the string " AAA'” 

END 



This FORTRAN example generates the following output: 


The blank character matches the 2nd character in 
the string " ABC" 

The character "A" matches the Oth character in 
the string " AAA" 
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LIB$SPANC—Skip Selected Characters 



LIB$SPANC is used to skip a specified set of characters in the 
source string. LIB$SPANC makes the VAX SPANC instruction 
available as a callable procedure. 

FORMAT 

LIB$SPANC src-str,table-arr,mask 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

The relative position in the source string of the character that terminated the 
operation is returned if such a character is found. Otherwise, zero is returned. 
If the source string has a zero length, then a zero is returned. 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string used by LIB$SPANC to index into table-arr. The src-str 
argument contains the address of a descriptor pointing to this source string. 

table-arr 

VMS Usage: vector_byte_unsigned 

type: byte (unsigned) 

access: read only 

mechanism: by reference, array reference 

Table that LIB$SPANC indexes into and ANDs with the mask byte. The 
table-arr argument contains the address of an unsigned byte array that is this 
table. 

mask 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Mask that is ANDed with bytes in table-arr. The mask argument contains 
the address of an unsigned byte that is this mask. 

DESCRIPTION 

LIB$SPANC uses successive bytes of the string specified by src-str to index 
into a table. The byte selected from the table is ANDed with the mask byte. 

The operation is terminated when the result of the AND is zero. 
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CONDITION None. 

VALUES 

RETURNED 


EXAMPLE 

!♦ 

! This FORTRAN program demonstrates how to use 
! LIB$SCANC and STR$UPCASE. 

i 

! Declare the Run-Time Library routines to be used. 


INTEGERS STRIUPCASE 
INTEGER*4 LIB$SCANC 
INTEGER*4 LIB$SPANC 


! Translate to upper case 
! Look lor characters 
! Skip over characters 


! ♦ 

! Declare the alphabet from which "words" are constructed. 

i - 


CHARACTER*(38) ALPHABET 

DATA ALPHABET /'ABCDEFGHIJKLMN0PQRSTUVWXYZO123456789$_'/ 


!♦ 


Local variable declarations 


INTEGER*4 WORD.COUNT /0/ 
INTEGER+4 WORD.LENGTH /0/ 
INTEGER*4 TOTAL.LENGTH /0/ 
INTEGER*4 START.POS /0/ 

INTEGER*4 END.POS /0/ 

REAL*4 AVERAGE.LENGTH /0.0/ 
CHARACTER * 80 LINE ! 

BYTE MATCH.TABLE(0:255) /256*0/ 


! Count of words found 
! Length of a word 
! Sum of word lengths 
! Position of start of word 
! Position of end of word 
! Average length of words 
Line to examine for words 
! Match table for scanning 


! + 

! The routines LIB$SCANC and LIB$SPANC require a table with an entry 
! for each possible character. Create a match table from ALPHABET 
! with an entry of 1 if the character is in ALPHABET, 0 otherwise. 

! MATCH.TABLE has already been initialized to zeros. 

i - 


DO I = 1, LEN(ALPHABET) 

MATCH.TABLE(ICHAR(ALPHABET(1:1))) = 1 
END DO 


!♦ 

! Loop forever finding words in LINE. When LINE is exhausted. 
! indicated by a START.POS of zero, read another one. Upon 
! end-of-file, leave the loop and print the statistics, 
i - 


OPEN( UNIT = 1, FILE = 'TEST.DAT', TYPE = 'OLD' ) 

DO WHILE (.TRUE.) 

DO WHILE (START.POS .EQ. 0) ! Get a new line 

READ (1,'(A)',END=900) LINE ! If EOF, skip to 900 
CALL STRIUPCASE (LINE,LINE) ! Convert to upper 

! case for matching 

START.POS = LIBISCANC (LINE.MATCH.TABLE,1) ! Find beginning 

END DO ! of first word 


! + 

! START.POS now points to the beginning of a word. Call LIB$SPANC to 
! find the first character that is not part of the word. Set 
! START_P0S to beginning of next word. If LIB$SPANC does not 
! find a non-word character, it returns zero. 


END.POS = 

1 START_PQS + LIBISPANC (LINE(START_POS:). MATCH.TABLE,1) - 1 

IF (END.POS .LT. START.POS) THEN ! Word goes to end of line 
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WORD.LENGTH « (LEN(LINE) ♦ 1) - START.POS 

START.POS = 0 ! Indicate line exhausted 

ELSE 

WORD.LENGTH = END.POS - START.POS 
START.POS = 

1 END.POS + LIB$SCANC (LINE(END.POS:),MATCH.TABLE,1) - 1 

IF (START.POS .LT. END.POS) START.POS = 0 ! No more words on line 
END IF 

!♦ 

! Update count and length statistics. 

! - 

WORD.COUNT = WORD.COUNT + 1 
TOTAL.LENGTH = TOTAL.LENGTH + WORD.LENGTH 
END DO 

900 CONTINUE 
! + 

! Compute average word length and display statistics. 

; - 

IF (WORD.COUNT .NE. 0) 

1 AVERAGE.LENGTH = FLOAT(TOTAL.LENGTH) / FLOAT(WORD.COUNT) 

TYPE 901,WORD.COUNT,AVERAGE.LENGTH 

901 FORMAT (IX,110,' words found, average length was 

1 F4.1,' letters.') 

CLOSE (1) 

END 


This FORTRAN program reads text from the default input unit and looks for 
words. A word is defined as a string containing only the characters A to Z 
(uppercase or lowercase), 0 to 9, and the dollar sign ($) and underscore (_) 
symbols. The program reports the total number of words found and their 
average length. 

The program uses three Run-Time Library procedures: STR$UPCASE, 
LIB$SCANC, and LIBSSPANC. 

1 The string is converted to uppercase using STR$UPCASE so that the 
search for words will ignore the case of letters. 

2 LIB$SCANC searches through the string for one of a set of characters, the 
set being specified as nonzero elements in a 256-byte table. 

3 Similarly, LIB$SPANC uses the VAX SPANC instruction to search through 
a string for a character whose table entry is not zero. 

The value returned by each procedure is the index into the string where the 
first matching (or nonmatching) character was found, or zero if no match was 
found. 

The output generated by this FORTRAN program is as follows: 

12 words found, average length was 4.2 letters. 
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LIB$SPAWIM—Spawn Subprocess 



LIB$SPAWN requests the command language interpreter (CLI) 
of the calling process to spawn a subprocess for executing CLI 
commands. LIB$SPAWN provides the same function as the DCL 
SPAWN command. 

FORMAT 

LIB$SPAWN [command-string][,input-file] 

[, output-file] [, flags] [, process-name] 

[, process-id] [, completion-status] 

[, completion-efn] [, completion-astadr] 

[, completion-astarg] [, prompt] [, cli] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

command-string 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

CLI command to be executed by the spawned subprocess. The command¬ 
string argument is the address of a descriptor pointing to this CLI command 
string. If omitted, commands are taken from the file specified by input-file. 

in put-file 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Equivalence name to be associated with the logical name SYS$INPUT in the 
logical name table for the subprocess. The input-file argument is the address 
of a descriptor pointing to this equivalence string. If omitted, the default is 
the caller's SYS$INPUT. 

output-file 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Equivalence name to be associated with the logical names SYS$OUTPUT and 
SYS$ERROR in the logical name table for the subprocess. The output-file 
argument is the address of a descriptor pointing to this equivalence string. If 
omitted, the default is the caller's SYS$OUTPUT. 
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flags 

VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Flag bits that designate optional behavior. The flags argument is the address 
of an unsigned longword that contains these flag bits. By default, all flags are 
clear. 


These flags are defined as follows: 


Bit 

~ 

1 


2 


3 


4 


5 


Symbol 

Meaning 

NOWAIT 

If set, the calling process continues executing in parallel 
with the subprocess. If clear, the calling process hibernates 
until the subprocess completes. 

NOCLISYM 

If set, the spawned subprocess does not inherit CLI 
symbols from its caller. If clear, the subprocess inherits all 
currently defined CLI symbols. You may want to specify 
NOCLISYM to help prevent commands redefined by symbol 
assignments from affecting the spawned commands. 

NOLOGNAM 

If set, the spawned subprocess does not inherit process 
logical names from its caller. If clear, the subprocess 
inherits all currently defined process logical names. 

You may want to specify NOLOGNAM to help prevent 
commands redefined by logical name assignments from 
affecting the spawned commands. 

NOKEYPAD 

If set, the keypad symbols and state are passed to the 
subprocess. If not set, the keypad settings are not passed 
to the subprocess. 

NOTIFY 

If set, a message is broadcast to SYS$OUTPUT when the 
subprocess completes or aborts. If not set, no message is 
broadcast. This bit should not be set unless the NOWAIT 
bit is also set. 

NOCONTROL 

If set, no carriage-return/line-feed is prefixed to any prompt 
string. If not set, a carriage-return/line-feed is prefixed to 
any prompt string specified. 


Bits 6 through 31 are reserved for future expansion and must be zero. 
Symbolic flag names are defined in STARLET. They are CLI$M_NOWAIT, 
CLI$M_NOCLISYM, CLI$M_NOLOGNAM, CLI$M_NOKEYPAD, CLI$M_ 
NOTIFY, and CLI$M_NOCONTROL. 


process-name 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Name defined for the subprocess. The process-name argument is the address 
of a descriptor pointing to this name string. If omitted, a unique process name 
will be generated. If you supply a name and it is not unique, LIB$SPAWN 
will return the condition value SS$_DUPLNAM. 
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process-id 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

Process identification of the spawned subprocess. The process-id argument is 
the address of an unsigned longword that contains this process identification 
value. 

This process identification value is meaningful only if the NOWAIT flags bit 
is set. 

completion-status 

VMS Usage: longword__unsigned 
type: longword (unsigned) 

access: write only 

mechanism: by reference 

The final completion status of the subprocess. The completion-status 
argument is the address of an unsigned longword. LIB$SPAWN writes 
the address of the final completion status of the subprocess into completion- 
status. 

If the NO WAIT flags bit is set, this value is not stored until the subprocess 
completes; use the completion-efn or completion-astadr arguments to 
determine when the subprocess has completed. 

completion-efn 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

The number of a local event flag to be set when the spawned subprocess 
completes. The completion-efn argument is the address of an unsigned byte 
that contains this event flag number. If omitted, no event flag is set. 

Specifying completion-efn is meaningful only if the NO WAIT flags bit is set. 

completion-astadr 

VMS Usage: procedure 
type: procedure entry mask 

access: call without stack unwinding 

mechanism: by reference 

Entry mask of a procedure to be called by means of an AST when the 
subprocess completes. The completion-astadr argument is the address of this 
procedure entry mask. 

Specifying completion-astadr is meaningful only if the NO WAIT flags bit is 
set. 

completion-astarg 

VMS Usage: user_arg 
type: unspecified 

access: read only 

mechanism: unspecified 

A value to be passed to the AST procedure. Typically, the completion-astarg 
argument is the address of a block of storage the AST procedure will use. 
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Specifying completion-astarg is meaningful only if the NO WAIT flags bit is 
set and if completion-astadr has been specified. 


prompt 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Prompt string to use in the subprocess. The prompt argument is the address 
of a descriptor pointing to this prompt string. If omitted, the subprocess will 
use the same prompt string that the parent process uses. 


cli 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification for the command language interpreter (CLI) to be run in the 
subprocess. The cli argument is the address of this file specification string's 
descriptor. The CLI specified must reside in SYS$SYSTEM with a file type of 
EXE, and it must be installed. No directory or file type may be specified. 


If omitted, the subprocess will use the same CLI as the parent process. If 
specified, no context will be copied to the subprocess. 


DESCRIPTION The subprocess created by LIB$SPAWN inherits the following attributes from 

the caller's environment: 

• Process logical names 

• Global and local CLI symbols 

• Default device and directory 

• Process privileges 

• Process nondeductible quotas 

• Current command verification setting 

The subprocess does not inherit process-permanent files, nor procedure or 
image context. 

If neither command-string nor input-file is present, command input will 
be taken from the parent terminal. If both command-string and input-file 
are present, the subprocess will first execute command-string and then read 
from input-file. If only command-string is specified, the command will be 
executed and the subprocess will be terminated. If input-file is specified, 
the subprocess will be terminated by either a LOGOUT command or an 
end-of-file. 

The subprocess does not inherit process-permanent files, nor procedure or 
image context. No LOGIN.COM file is executed. 

Unless the NOWAIT flags bit is set, the caller's process is put into hibernation 
until the subprocess completes. Because the caller's process hibernates in 
supervisor mode, any user-mode ASTs queued for delivery to the caller 
will not be delivered until the caller reawakes. Control can also be restored 
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to the caller by means of an ATTACH command or by a suitable call to 
LIB$ATTACH from the subprocess. 

This procedure is supported for use only with the DCL command language 
interpreter. If used when the current CLI is MCR, the error status LIB$_ 
NOCLI will be returned. 

If an image is run directly as a subprocess or as a detached process, there 
is no CLI present to perform this function. In such cases the error status 
LIB$_NOCLI is returned. 

Programs depending on embedded DCL commands may not function 
properly when run under other command language interpreters that may 
be supported by future versions of VAX/VMS. 

See the VAX/VMS DCL Dictionary for a complete description of the SPAWN 
command. 


CONDITION SS$_NORMAL 
VALUES SSS—ACCVIO 

RETURNED 

SS$_DUPLNAM 


fac$_xxx 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_NOCLI 


Procedure successfully completed. 

Access violation. One of the string arguments to 
LIBSSPAWN could not be read, or completion- 
status could not be written. 

Duplicate process name. If the argument process- 
name was specified, it duplicated an existing 
process name. If process-name was omitted, 
LIB$SPAWN was unable to create a unique name 
for the subprocess. 

Other error trying to create subprocess. 

Invalid argument. The optional argument flags was 
specified and a bit other than bits 0 through 5 was 
set. 

Invalid string descriptor. One of the string 
arguments had an invalid descriptor. 

No CLI present to perform function. The calling 
process did not have a CLI to perform the function, 
or the CLI did not support the request type. Note 
that an image run as a subprocess or detached 
process does not have a CLI. 


If an error is encountered while trying to create the subprocess, the status 
value for that error is returned by LIB$SPAWN. 


EXAMPLE 


ISTAT=LIB$SPAWN(,,,CLI$M_NOKEYPAD.'> ') 

IF (.NOT. ISTAT) CALL LIB$STOP(*/.VAL(ISTAT)) 

This FORTRAN fragment illustrates a call to LIB$SPAWN from within a 
FORTRAN program. A subprocess is spawned taking input from SYS$INPUT 
and giving output to SYS$OUTPUT. The keypad state is not passed to the 
subprocess. A prompt string of "> " is specified for the subprocess. 
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LI B$STAT_TIM ER—Statistics, Return 

Accumulated Times 
and Counts 

LIB$STAT_TIMER returns to its caller one of five available statistics. 
Unlike LIB$SHOW_TIMER, which formats the values for output, 
LIB$STAT_TIMER returns the value as an unsigned longword or 
quad word. 


FORMAT LIB$STAT_TIMER code, value [,handle-adr] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


code 

VMS Usage: 
type: 
access: 
mechanism: 


function-code 
longword integer (signed) 
read only 
by reference 

Code which specifies the statistic to be returned. The code argument contains 
the address of a signed longword integer that is this code. It must be an 
integer from 1 to 5. 

The following values are allowed for code. 


Value Statistic returned 

1 Elapsed time (quadword, in system time format) 

2 CPU time (longword, in 10 millisecond increments) 

3 Buffered I/O (longword) 

4 Direct I/O (longword) 

5 Page faults (longword) 


value 


VMS Usage: 
type: 
access: 
mechanism: 


user_arg 
unspecified 
write only 
by reference 


The statistic returned by LIB$STAT_TIMER. The value argument contains 
the address of a longword or quadword that is this statistic. All statistics are 
longword integers except elapsed time, which is a quadword. 


See the VAX/VMS System Services Reference Manual for more details on the 
system time format. 
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DESCRIPTION 


CONDITION 

VALUES 

RETURNED 


handle-adr 


VMS Usage: address 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Pointer to a block of storage. The optional handle-adr argument contains the 
address of an unsigned longword that is this pointer. 


If handle-adr is specified, LIB$STAT_TIMER assumes that LIB$INIT_TIMER 
has been called with the same value of handle-adr. Handle-adr is an 
optional argument. If it is not specified, LIB$STAT_TIMER uses internal 
storage. 


Only one of the five statistics is returned by each call to LIB$STAT_TIMER. 

The elapsed time is returned in the system quadword format. Therefore 
the receiving area should be eight bytes long. All other returned values are 
longwords. 

LIB$SHOW_TIMER and LIB$STAT_TIMER are relatively simple tools for 
testing the performance of a new application. To obtain more detailed 
information, use LIB$GETJPI (Get Job/Process Information) or the VMS 
system service SYS$GETTIM (Get Time). 

The following summary illustrates the differences between LIB$SHOW_ 
TIMER and LIB$STAT_TIMER. 


Code 

Statistic 

Format for 
LIB$SHOW_TIMER 

Format for 
LIB$STAT_TIMER 

1 

Elapsed real time 

hhhh:mm:ss.cc 

Quadword in system 
time format 

2 

Elapsed CPU time 

hhhh:mm:ss.cc 

Longword in 10- 
millisecond increments 

3 

Count of buffered I/O 
operations 

nnnn 

Longword 

4 

Count of direct I/O 
operations 

nnnn 

Longword 

5 

Count of page faults 

nnnn 

Longword 


When you call LIB$INIT_TIMER, you must use the optional handle-adr 
argument only if you want to keep several sets of statistics simultaneously. 
This argument points to a block in heap storage where the statistics are to be 
stored. 

You need to call LIB$FREE_TIMER only if you have specified handle-adr in 
LIB$INIT_TIMER and you wish to deallocate all heap storage resources. In 
most cases, the implicit deallocation at program exit time will be sufficient. 


SS$_NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. Either code or handle-adr is 

invalid. 
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EXAMPLE 

PROGRAM STAT_TIMER(INPUT,OUTPUT); 

{+> 

{ This PASCAL example program demonstrates the use of 
{ LIB$STAT_TIMER. 

<_> 

TYPE 

BYTE = [BYTE] 0..255; 

WORD = [WORD] 0..65535; 

QUADWORD_SYSTEM_TIME = [QUAD] RECORD 
FIRST.LONGWORD : UNSIGNED; 

SECOND.LONGWORD : UNSIGNED; 

END; 

VAR 

ELAPSED_REAL_TIME : QUADWORD_SYSTEM_TIME; 

ELAPSED.STRING : VARYING [32] OF CHAR; 

PAGE.FAULT.COUNT : UNSIGNED; 

RETURNED.STATUS : UNSIGNED; 

[EXTERNAL] FUNCTION LIB$INIT_TIMER( 

HANDLE.ADR : [REFERENCE] UNSIGNED := ‘/.IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STAT_TIMER( 

CODE : INTEGER; 

VALUE : [UNSAFE,REFERENCE] PACKED ARRAY [L..U:INTEGER] OF BYTE; 

HANDLE.ADR : [REFERENCE] UNSIGNED := 7.IMMED 0 
) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION.STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 

FAO.ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$SYS_ASCTIM( 

OUT.LEN : [REFERENCE] WORD := 7.IMMED 0; 

VAR DST.STR : PACKED ARRAY [L..U:INTEGER] OF CHAR; 

USER.TIME : QUADWORD_SYSTEM_TIME := ‘/.IMMED 0; 

CNV.FLG : UNSIGNED := ‘/.IMMED 0 
) : INTEGER; EXTERNAL; 

BEGIN 

<+> 

{ Call LIB$INIT_TIMER to initialize RTL internal counters. 

{-> 

RETURNED.STATUS := LIB$INIT_TIMER; 

IF NOT ODD(RETURNED.STATUS) 

THEN 

LIB$STOP(RETURNED.STATUS); 

{♦> 

{ Print a line of text to waste time. 

{-> 

WRITELN('Spend time to acquire elapsed real time and page faults'); 

{♦> 

{ Call LIB$STAT_TIMER to retrieve statistics values. 

{-> 

RETURNED.STATUS := LIB$STAT_TIMER(1.ELAPSED.REAL.TIME); 

IF NOT ODD(RETURNED.STATUS) 

THEN 

LIB$STOP(RETURNED.STATUS); 

RETURNED.STATUS := LIB$STAT_TIMER(5,PAGE.FAULT.COUNT); 

IF NOT ODD(RETURNED.STATUS) 

THEN 

LIB$STOP(RETURNED.STATUS); 

{♦> 

{ Print the statistics retrieved from LIB$STAT_TIMER. 

{-> 

WRITELN('Page fault count is ',PAGE.FAULT.COUNT:1); 
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RETURNED.STATUS := LIB$SYS_ASCTIM( 

ELAPSED.STRING.LENGTH, 
ELAPSED.STRING.BODY, 
ELAPSED.REAL.TIME, 
l); 

IF NOT ODD(RETURNED.STATUS) 

THEN 

LIB$ST0P(RETURNED.STATUS); 

WRITELNCElapsed real time is ',ELAPSED_STRING); 
END. 


This PASCAL program demonstrates the use of LIB$STAT_TIMER. The 
output generated by this program is as follows: 

Spend time to acquire elapsed real time and page faults 

Page fault count is 22 

Elapsed real time is 00:00:00.61 
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LIB$STAT_VM—Return Virtual Memory 

Statistics 

LIB$STAT_VM returns to its caller one of six statistics available 
from calls to LIB$GET_VM/LIB$FREE_VM and LIB$GET_VM_PAGE 
/LIB$FREE_VM_PAGE. Unlike LIB$SHOW_VM, which formats the 
values for output and displays them on SYS$OUTPUT, LIB$STAT_ 
VM returns the statistic in the value argument. Only one of the 
statistics is returned by each call to LIB$STAT_VM. 


FORMAT LIB$STAT_VM code,value 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond_value 
longword (unsigned) 
write only 
by value 


ARGUMENTS code 


VMS Usage: 
type: 
access: 
mechanism: 


function_code 
longword integer (signed) 
read only 
by reference 


Code specifying which statistic is to be returned. The code argument contains 
the address of a signed longword integer that is this code. 


Code Statistic 

1 Number of successful calls to LIB$GET_VM 

2 Number of successful calls to LIB$FREE_VM 

3 Number of bytes allocated by LIB$GET_VM but not yet deallocated by 

LIB$FREE_VM 

5 Number of calls to LIB$GET_VM_PAGE 

6 Number of calls to LIB$FREE_VM_PAGE 

7 Number of pages allocated by LIB$GET_VM_PAGE but not yet 
deallocated by LIB$FREE VM PAGE 


Note that it is invalid to omit code or to give a code of 0 or 4. 


value 


VMS Usage: 
type: 
access: 
mechanism: 


longword—signed 
longword integer (signed) 
write only 
by reference 


Value of the statistic returned by LIB$STAT_VM. The value argument 
contains the address of a signed longword integer that is this value. 
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DESCRIPTION LIB$STAT_VM returns to its caller one of six available statistics. Unlike 

LIB$SHOW_VM which formats the values for output, LIB$STAT_VM returns 
the value to a location specified as an argument. 

Only one of the six statistics can be returned by one call to LIB$STAT_VM. 
Code must be one of six values described for LIB$SHOW_VM. A code value 
of 0 or 4 is invalid. 

Unlike LIB$SHOW_VM, which produces ASCII values for output, 
LIB$STAT__VM returns the value in binary form to a location specified 
as an argument. 


CONDITION SS$_NORMAL 
VALUES LIB$_INVARG 

RETURNED 


Procedure successfully completed. 

Invalid argument. The value of Code was not one 
of the values allowed by LIB$STAT_VM. 
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LIB$STOP—Stop Execution and Signal the 



Condition 

LIB$STOP generates a signal that indicates that an exception 
condition has occurred in your program. Exception conditions 
signaled by LIB$STOP cannot be continued from the point of the 
signal. 

FORMAT 

LIB$STOP condition-value 1 [,number 1 ] 

[, FA O-arg 1FA O-argn 1 ] 

[, condition-value2] [, number2] 

[, FA O-arg 2. ..,FA O-argn 2] 

Only the condition-valuel argument must be specified; other arguments are 
optional. The numberl argument, if specified, contains the number of FAO 
arguments that will be associated with condition-valuel. The condition- 
value2 argument is optional; it may be specified with or without the number2 
or FAO-arg2 arguments. The number2 argument, if specified, contains the 
number of FAO arguments that will be associated with condition-value2. 

You may specify condition-value3, condition-value4, condition-value5, and 
so on, along with their corresponding number and FAO arguments. 

RETURNS 

LIB$STOP generates a signal and stops execution of the calling program. No 
condition values are returned. 

ARGUMENTS 

condition-value 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by value 

VAX 32-bit condition value. The condition-value argument is an unsigned 
longword that contains this condition value. 

Section 7.1.2 explains the format of a condition value. 

number 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by value 

Number of FAO arguments associated with the condition value. The number 
argument is a a signed longword integer that contains this number. If omitted 
or specified as zero, no FAO arguments follow. 
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FAO-arg(s) 

VMS Usage: varying_arg 
type: unspecified 

access: read only 

mechanism: by value 

Additional FAO (formatted ASCII output) argument(s) which are associated 
with the specified condition value. The FAO-arg(s) argument is the address 
of a signed longword integer or a character string that contains these 
additional FAO arguments. 

Section 7.1.5 explains the message format. 

DESCRIPTION 

LIB$STOP is called whenever your program must indicate an exception 
condition because it is impossible to continue execution or return a status 
code to the calling program. 

LIB$STOP scans the stack frame by frame, starting with the most recent 
frame, calling each established handler (see Section 7.1.3). LIB$STOP 
guarantees that control will not return to the caller. 

The LIB$STOP argument list, the Program Counter (PC) and Processor Status 
Longword (PSL) of the caller are appended to build the signal argument 
vector. 

The severity of condition-value is forced to SEVERE before each call to a 
handler. 

If any handler attempts to continue by returning a success completion code, 
the error message ATTEMPT TO CONTINUE FROM STOP is printed and 
your program exits. 

If the handler called by LIB$STOP calls SYS$UNWIND, control will not 
return to LIB$STOP's caller, thus changing the program flow. A handler can 
also modify the saved copy of R0/R1 in the mechanism vector, changing 
registers RO and R1 after the stack has been unwound. If a handler does 
neither of these things, then all registers including R0/R1 and the hardware 
condition codes are preserved. 

The only way a handler can prevent the image from exiting after a call to 
LIB$STOP is to unwind the stack using the SYS$UNWIND system service. 

CONDITION 

VALUES 

RETURNED 

None. 
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EXAMPLE 


10 EXTERNAL LONG FUNCTION LIB$RESERVE_EF 
DECLARE LONG RET_STATUS 
RET.STATUS = LIB$RESERVE_EF ( 2*/. ) 

IF (RET.STATUS AND 1%) * 0*/. THEN 
CALL LIBISTOPC RET.STATUS BY VALUE ) 

END IF 

PRINT "Event flag 2 reserved successfully" 
END 


This BASIC example program uses LIB$STOP to stop executing if an error 
is signaled. This BASIC program tries to reserve an event flag that is not 
accessible to user programs, thus ensuring that an error will be signaled. 

The output generated by this BASIC program is as follows: 


7.LIB-F-EF.ALRRES, event flag already reserved 
y,TRACE-F-TRACEBACK, symbolic stack dump follows 
module name routine name line 

2822XBLST$MAIN 2822XBLST$MAIN 6 


rel PC abs PC 
00000044 00000644 
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LIB$SUBX—Multiple-Precision Binary 
Subtraction 

LIB$SUBX performs subtraction on signed two’s complement 
integers of arbitrary length. 


FORMAT LIB$SUBX a ,b ,diff[,len] 


RETURNS 


VMS Usage: 
type: 
access: 
mechanism: 


cond—value 
longword (unsigned) 
write only 
by value 


ARGUMENTS 


a 

VMS Usage: 
type: 
access: 
mechanism: 


vector_longword_signed 
longword integer (signed) 
read only 

by reference, array reference 

Minuend; a multiple-precision, signed two's complement integer. The a 
argument is the address of an array of signed longword integers that contains 
the minuend. 


b 

VMS Usage: vector_longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference, array reference 

Subtrahend; a multiple-precision, signed two's complement integer. The b 
argument is the address of an array of signed longword integers that contains 
the subtrahend. 

diff 

VMS Usage: vector_longword_signed 
type: longword integer (signed) 

access: write only 

mechanism: by reference, array reference 

Difference; a multiple-precision, signed two's complement integer result. The 
diff argument is the address of an array of signed longword integers that 
contains the difference. 


len 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Length in longwords of the arrays to be operated on by LIB$SUBX. The 
len argument contains the address of a signed longword integer that is this 
length. Len must not be negative. The default length is 2. 
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DESCRIPTION LIB$SUBX performs subtraction on signed two's complement integers of 

arbitrary length. The integers are located in arrays of longwords. The higher 
addresses contain the higher precision parts of the values. The highest- 
addressed longword contains the sign and 31 bits of precision. The remaining 
longwords contain 32 bits of precision in each. The number of longwords to 
be operated on is given by the optional argument, len. The default length is 
2, which corresponds to the VAX quadword data type. 


CONDITION SS$_NORMAL 
VALUES SS$_INTOVF 

RETURNED 

LIB$_INVARG 


Routine successfully completed. 

Integer overflow. The result is correct, except that 
the sign bit is lost. 

Invalid argument. Length is negative. The output 
array is unchanged. 


EXAMPLE 


C+ 

C This FORTRAN example program demosntrates the use of LIB$SUBX. 

C- 

INTEGER A(2),B(2),C(2).RETURN 
C+ 

C Let "A" have the value 72057594037927937 = •1000000000000001•x. 

C Let "B" have the value 4294967295 = •00000000FFFFFFFF 1 x. 

c- 

A(l) = '00000001'x 
A(2) = '10000000'x 
B(l) = *FFFFFFFF'x 
B(2) * 1 00000000'x 
C+ 

C Then "A" - "B" is 72057589742960642. 

C- 

RETURN = LIB$SUBX(A,B.C) 

TYPE *,' ' 

TYPE *,•Let A = 72057594037927937 and B = 4294967295.' 

TYPE *,'Then C = A - B = 72057589742960642.' 

TYPE 2,C(2),C(i) 

2 FORMAT(' 72057589742960642 is represented as ',1H'.Z8,Z8.3H'x.) 

TYPE *, SIHThat is. C(2) = 1 OFFFFFFF'x and C(l) = '00000002'x. 
END 


This FORTRAN example demonstrates how to call LIB$SUBX. The output 
generated by this program is as follows: 

Let A = 72057594037927937 and B = 4294967295. 

Then C = A - B = 72057589742960642. 

72057589742960642 is represented as ' FFFFFFF 2'x. 

That is. C(2) = •OFFFFFFF'x and C(l) = '00000002'x. 
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LIB$SYS_ASCTIM—Invoke $ASCTIM to 

Convert Binary Time 
to ASCII String 


LIB$SYS_ASCTIM calls the system service $ASCTIM to convert 
a binary date and time value, returning the ASCII string using the 
semantics of the caller's string. 

FORMAT 

LI B$SYS-ASCTIM [out-len ], dst-str [, user-time] 

[,cnv-flg] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 


ARGUMENTS 


out-len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of bytes written into dst-str, not counting padding in the case of a 
fixed-length string. The out-len argument contains the address of a signed 
word integer that is this number. 


If the input string is truncated to the size specified in the dst-str descriptor, 
out-len is set to this size. Therefore, out-len can always be used by the 
calling program to access a valid substring of dst-str. 


dst-str 

VMS Usage: time_name 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$SYS_ASTIM writes the ASCII time string. 
The dst-str argument contains the address of a descriptor pointing to the 
destination string. 


user-time 

VMS Usage: date_time 
type: quadword integer (signed) 

access: read only 

mechanism: by reference 

Value that LIB$SYS_ASCTIM converts to ASCII string form. The user-time 
argument contains the address of a signed quadword integer that is this value. 


If zero or no address is specified, the current system date and time are 
returned. A positive value represents an absolute time. A negative value 
represents a delta time. Delta times must be less than 10,000 days. 
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cnv-flg 


VMS Usage: mask_longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Conversion indicator. The cnv-flg argument contains the address of an 
unsigned longword that is this conversion indicator. 


A value of 1 causes only the hour, minute, second, and hundredths of a 
second to be returned, depending on the length of the buffer. A value of zero 
(the default) causes the full date and time to be returned, depending on the 
length of the buffer. 

Argument cnv-flg is passed to LIB$SYS_ASCTIM by reference and is 
changed to value for use by $ASCTIM. 


DESCRIPTION See the VAX/VMS System Services Reference Manual for a complete description 

of $ASCTIM. 


CONDITION 

SS$_NORMAL 

Routine successfully completed. 

VALUES 

LIB$_STRTRU 

Routine successfully completed, but the source 

RETURNED 


string was truncated. 


LIB$_FATERRLIB 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 


LIB$_INSVIRMEM 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 


LIB$_INVSTRDES 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 


SS$_IVTIME 

The specified delta time is greater than or equal to 
10,000 days. 
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LIB$SYS_FAO—Invoke $FAO System 

Service to Format Output 

LIB$SYS_FAO calls $FAO, returning a string in the semantics you 
provide. If called with other than a fixed-length string for output, the 
length of the resultant string is limited to 256 bytes and truncation 
will occur. 


FORMAT 

LIBSSYS 

_FAO ctr-str[,out-len],out-buf[,p 1,...,pn] 

RETURNS 

VMS Usage: 

cond_value 


type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS 


ctr-str 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
read only 
by descriptor 

ASCII control string, consisting of the fixed text of the output string and FAO 
directives. The ctr-str argument contains the address of a descriptor pointing 
to this control string. 


out-len 

VMS Usage: 
type: 
access: 
mechanism: 


word—integer 
word integer (signed) 
write only 
by reference 

Length of the output string. The out-len argument contains the address of a 
signed word integer that is this length. 


out-buf 

VMS Usage: 
type: 
access: 
mechanism: 


char_string 
character string 
write only 
by descriptor 

Fully formatted output string returned by LIB$SYS_FAO. The out-buf 
argument contains the address of a descriptor pointing to this output string. 


pi—pn 

VMS Usage: 
type: 
access: 
mechanism: 


varying—arg 
unspecified 
read only 
unspecified 

Directive argument(s) contained in longwords. Depending on the directive, 
a p argument can be a value to be converted, the address of the string to be 


RTL-312 







Run-Time Library Routines 

LI B$SYS_FAO 


inserted, or a length or argument count. The passing mechanism for each of 
these arguments should be the one expected by the $FAO system service. 


DESCRIPTION See the VAX/VMS System Services Reference Manual for a complete description 

of $FAO. 


CONDITION SS$_NORMAL 

VALUES SS$_BUFFEROVF 

RETURNED 

LIB$_STRTRU 

SS$_BADPARAM 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Successfully completed, but the formatted output 
string overflowed the output buffer and was 
truncated. 

Success, but the source string was truncated on 
copy. 

An invalid directive was specified in the FAO 
control string. 

Insufficient virtual memory to allocate dynamic 
string. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$SYS_FAOL—Invoke $FAOL System 

Service to Format Output 

LIB$SYS_FAOL calls the system service routine $FAOL, returning 
the string in the semantics you provide. If called with other than a 
fixed-length string for output, the length of the resultant string is 
limited to 256 bytes and truncation will occur. 


FORMAT 

LIB$SYS_FAOL ctr-str,[out-len],out-buf,p1 -pn 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

ctr-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

ASCII control string, consisting of the fixed text of the output string and FAO 
directives. The ctr-str argument contains the address of a descriptor pointing 
to this control string. 


out-len 

VMS Usage: word-integer 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Length of the output string. The out-len argument contains the address of a 
signed word integer that is this length. 


out-buf 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Fully formatted output string returned by LIB$SYS_FAOL. The out-buf 
argument contains the address of a descriptor pointing to this output string. 


pi—pn 

VMS Usage: varying—arg 

type: longword (unsigned) 

access: read only 

mechanism: by reference, array reference 

Directive argument(s). The pi—pn arguments are contained in an array of 
unsigned longword directive arguments. Depending on the directive, a p 
argument can be a value to be converted, the address of the string to be 
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inserted, or a length or argument count. The passing mechanism for each of 
these arguments should be the one expected by the $FAOL system service. 


DESCRIPTION See the VAX/VMS System Services Reference Manual for a complete description 

of $FAOL. 


CONDITION SS$_NORMAL 

VALUES SS$_BUFFEROVF 

RETURNED 

LIB$_STRTRU 

SSS—BADPARAM 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Successfully completed, but the formatted output 
string overflowed the output buffer and was 
truncated. 

Success, but the source string was truncated on 
copy. 

An invalid directive was specified in the FAO 
control string. 

Insufficient virtual memory to allocate dynamic 
string. 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 
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LIB$SYS_GETMSG—Invoke $GETMSG 

System Service to 
Get Message Text 

LIB$SYS_GETMSG calls the System Service SGETMSG and returns 
a message string into dst-str using the semantics of the caller's 
string. 


FORMAT 

LIB$SYS 

_GETMSG msg-id,[msg-len],dst-str 



[, flags] [, out-arr] 

RETURNS 

VMS Usage: 

cond_value 

type: 

longword (unsigned) 


access: 

write only 


mechanism: 

by value 


ARGUMENTS 


msg-id 

VMS Usage: longword_signed 
type: longword integer (signed) 

access: read only 

mechanism: by reference 

Message identification to be retrieved by LIB$SYS_GETMSG. The msg-id 
argument contains the address of a signed longword integer that is this 
message identification. 


msg-len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of characters written into dst-str, not counting padding in the case of 
a fixed-length string. The msg-len argument contains the address of a signed 
word integer that is this number. 


If the input string is truncated to the size specified in the dst-str descriptor, 
msg-len is set to this size. Therefore, msg-len can always be used by the 
calling program to access a valid substring of dst-str. 


dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string. The dst-str argument contains the address of a descriptor 
pointing to this destination string. LIB$SYS_GETMSG writes the message 
that has been returned by $GETMSG into dst-str. 


RTL-316 









Run-Time Library Routines 

LIB$SYS_GETMSG 


flags 

VMS Usage: mask—longword 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Four flag bits for message content. The flags argument is the address of 
an unsigned longword that contains these flag bits. The default value is a 
longword with bits zero through 3 set to 1. The flags argument is passed to 
LIB$SYS_GETMSG by reference and changed to value for use by $GETMSG. 

Bit numbers, their values, and corresponding descriptions are listed below. 


Bit 

Value 

Description 

0 

1 

Include text of message 


0 

Do not include text of message 

1 

1 

Include message identifier 


0 

Do not include message identifier 

2 

1 

Include severity indicator 


0 

Do not include severity indicator 

3 

1 

Include facility name 


0 

Do not include facility name 


out-arr 

VMS Usage: longword—unsigned 

type: longword (unsigned) 

access: write only 

mechanism: by reference, array reference 

A 4-byte array to receive message-specific information. The out-arr argument 
contains the address of this array of unsigned longwords. 

The contents of this 4-byte array are as follows: 


Byte Contents 

0 Reserved 

1 Count of FAO arguments 

2 User value 

3 Reserved 


DESCRIPTION See the VAX/VMS System Services Reference Manual for a complete description 

of $GETMSG. 
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CONDITION SS$_NORMAL 

VALUES SS$_BUFFEROVF 

RETURNED 

SS$_MSGNOTFND 

LIB$_STRTRU 

LIB$_FATERRLIB 

LIB$_INSVIRMEM 

LIB$_INVSTRDES 


Procedure successfully completed. 

Successfully completed, but the resultant string 
overflowed the buffer provided and was truncated. 

Successfully completed, but the message code 
does not have an associated message on file. 

Successfully completed, but the source string was 
truncated. 

Fatal internal error. 

Insufficient virtual memory. 

Invalid string descriptor. 
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LIB$SYS_TRISILOG—Invoke $TRNLOG 
System Service to Translate Logical Name 


LIB$SYS_TRNLOG uses the system service $TRNLOG to translate 
a logical name, LIB$SYS_TRNLOG returns the logical name's 
translation using the semantics of the caller's string. 

FORMAT 

LI B$SYS_TR N LOG logical-name, [dst-len],dst-str 

[, table] [,acc-mode] [, dsb-msk] 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: ' write only 

mechanism: by value 


ARGUMENTS logical-name 

VMS Usage: logical_name 
type: character string 

access: read only 

mechanism: by descriptor 

Logical name. The logical-name argument contains the address of a 
descriptor pointing to this logical name string. 


dst-len 

VMS Usage: word-signed 
type: word integer (signed) 

access: write only 

mechanism: by reference 

Number of characters written into dst-str, not counting padding in the case of 
a fixed-length string. The dst-len argument contains the address of a signed 
word integer that is this number. 


If the input string is truncated to the size specified in the dst-str descriptor, 
dst-len is set to this size. Therefore, dst-len can always be used by the 
calling program to access a valid substring of dst-str. 


dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string into which LIB$SYS_TRNLOG writes the logical name 
translation. The dst-str argument contains the address of a descriptor 
pointing to this destination string. 
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table 

VMS Usage: byte_integer 
type: byte integer (signed) 

access: write only 

mechanism: by reference 

Logical name table number. The table argument contains the address of a 
signed byte integer that is this table number. 


acc-mode 

VMS Usage: access.mode 
type: byte integer (signed) 

access: write only 

mechanism: by reference 

Access mode of entry (process table only). The acc-mode argument contains 
the address of a signed byte integer that is this access mode. 

The access modes, their numeric values, and symbolic names are as follows: 


Mode 

Value 

Symbolic Name 

Kernel 

0 

PSL$C_KERNEL 

Executive 

1 

PSL$C_EXEC 

Supervisor 

2 

PSL$C_SUPER 

User 

3 

PSL$C_USER 


dsb-msk 

VMS Usage: byte.unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by reference 

Table search disable mask. The dsb-msk argument contains the address of 
an unsigned byte that is this mask. 


Argument dsb-msk is passed to this routine by reference and is changed to 
value for use by $TRNLOG. 


If the mask bits described below are set, the action described in the table 
occurs. 


Bit Action 

0 Do not search system logical name table 

1 Do not search group logical name table 

2 Do not search process logical name table 


DESCRIPTION See the VAX/VMS System Services Reference Manual for a complete description 

of STRNLOG. 
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CONDITION 

VALUES 

RETURNED 


SS$_NORMAL 

SSS—NOTRAN 

LIB$_STRTRU 

SS$_ACCVIO 

SS$_IVLOGNAM 

SS$_RESULTOVF 

LIB$_FATERRLIB 

LIB$_INVSTRDES 

LIB$_INSVIRMEM 


Procedure successfully completed. 

Successfully completed, but the input logical name 
string was placed in the output buffer because no 
equivalence name was found. 

Successfully completed, but the source string was 
truncated on copy. 

The caller cannot read the logical name string or 
the string descriptor, or cannot write the output 
length, output buffer, table, or access mode field. 

The specified logical name string has a length of 
zero or is greater than 255 characters. String was 
placed in the destination string buffer because no 
equivalence name was found. 

The destination string buffer has a length of zero, 
or it is smaller than the resultant string. 

Fatal internal error. An internal consistency check 
has failed. This usually indicates an internal error 
in the Run-Time Library and should be reported to 
DIGITAL in a Software Performance Report (SPR). 

Invalid string descriptor. A string descriptor has an 
invalid value in its DSC$B_CLASS field. 

Insufficient virtual memory. A call to LIB$GET_VM 
has failed because your program has exceeded the 
image quota for virtual memory. 
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LIB$TPARSE—Table-Driven Finite-State 

Parser 

LIB$TPARSE is a general-purpose, table-driven parser implemented 
as a finite-state automaton, with extensions that make it suitable 
for a wide range of applications. LIB$TPARSE parses a string and 
returns a message indicating whether or not the input string is valid. 

FORMAT 

LIB$TPARSE arg-blk ,state-tbl r key-tbl 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

arg-blk 

VMS Usage: address 
type: longword (unsigned) 

access: modify 

mechanism: by reference 

LIB$TPARSE argument block. The arg-blk argument contains the address of 
this argument block. 

The LIB$TPARSE argument block contains information about the state of the 
parse operation. It becomes the argument list presented to all action routines. 

Figure RTL-6 illustrates the format of the argument block. 
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Figure RTL-6 LIB$TPARSE Argument Block 

TPA$I_COUNT: 

TPA$I_OPTIONS: 

TPA$I_STRINGCNT: 

TPA$I_STRINGPTR: 

TPA$I_TOKENCNT: 

TPA$I_TOKENPTR: 

TPA$B_CHAR: 

TPA$I_NUMBER: 

TPA$I_PARAM: 

ZK-1929-84 


TPA$K_CO UNTO = 8 


Flag bits 


Length of input string 


Pointer to input string 


Length of current token 


Pointer to current token 


Character 


Unused 


Binary value of numeric token 


Argument supplied by user 


The fields of the argument block are explained in detail in the section entitled 
"The LIB$TPARSE Argument Block." 


state-tbl 

VMS Usage: address 
type: unspecified 

access: read only 

mechanism: by reference 

Starting state in the state table. The state-tbl argument is the address of this 
starting state. 


Usually, the name appearing as the first argument of the $INIT_STATE macro 
is used. 


key-tbl 

VMS Usage: 
type: 
access: 
mechanism: 


address 
unspecified 
read only 
by reference 


Keyword table. The key-tbl argument is the address of this keyword table. 


This name must be the same as that which appeared as the second argument 
of the $INIT_STATE macro. It is called with the address of an argument 
block, the address of a state table, and the address of a keyword table. The 
input string is specified as part of the argument block. 
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DESCRIPTION LIB$TPARSE analyzes an input string according to a set of states and 

transitions presented in a state table to determine whether the input string is 
valid according to the rules you have defined for the input language. 

The following sections explain in detail how LIB$TPARSE works and how to 
call it from both assembly and high-level languages. 

1 "How LIB$TPARSE Works" describes the data structures used by 
LIB$TPARSE and how LIB$TPARSE operates on them. 

2 "Coding and Using a Simple State Table" shows you how to construct and 
use a simple state table. 

3 "Using Advanced LIB$TPARSE Features" explains how to use 
subexpressions, abbreviations, action routines, and other advanced 
features. 

4 "State Table Object Representation" includes information of interest 
to the low-level language programmer, such as the state table object 
representation. 

How LIBSTPARSE Works 

There are three parts to any parsing operation. 

1 The string to be parsed. LIB$TPARSE accepts the input string as part of 
an argument block that contains additional information about the state 
of the parse—how much of the string has not been interpreted, what the 
current token is, and so forth. See the section entitled "The LIB$TPARSE 
Argument Block." 

2 The set of characters from which the input string is chosen, called the 
alphabet of your language. LIB$TPARSE recognizes the ASCII character 
set and provides symbolic names for the most common combinations 
of ASCII characters—alphabetic and alphanumeric strings, VMS 
symbols, numbers, and so on. See the section entitled "The Alphabet 
of LIB$TPARSE." 

3 The rules which govern how the alphabet is used—in other words, the 
language's syntax. You specify these rules in the state tables. (In a 
LIB$TPARSE state table, each state is simply a list of the transitions to 
other states.) See the section entitled "The State Tables." 

LIB$TPARSE reads the input string from left to right, dividing it into a set of 
tokens —substrings to be treated as logical entities. By default, LIB$TPARSE 
treats blanks as invisible separators; it takes all characters up to the next blank 
as a single token. You can use the TPA$V_BLANKS flag in the argument 
block to cause LIB$TPARSE to interpret the tokens differently; see the section 
entitled "Blanks in the Input String." 

LIB$TPARSE evaluates the transitions in the order in which they appear in 
the state, which corresponds to the order in which they were written in the 
source program. Each token is then evaluated against each possible transition 
in the current state. If it does not match, LIB$TPARSE attempts to match the 
next transition, until it runs out of transitions in the state. 

Each transition specifies what constitutes a valid token, what state is to 
be entered next, whether an action routine is to be called, and whether 
information is to be stored in a mask or mask-adr argument. By default, 
the next state is the state that follows the current state in the state table. No 
action routines are called, and no information is stored. LIB$TPARSE also 
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allows subexpression calls, which can change the order in which transitions 
are accepted; see the section entitled "Using Subexpressions." Action routines 
can also change the order in which transitions are accepted. The section 
entitled "Action Routines" explains how LIB$TPARSE processes action 
routines. 

LIB$TPARSE reads the input string, interprets the transitions in the state 
table, and calls the action routines (if any) until: 

1 It executes a transition to TPA$_EXIT (the string is valid) at main level 
(that is, while it is not processing a subexpression call). It returns with the 
value SS$_NORMAL. 

2 A transition or action routine requests that LIB$TPARSE consider the 
string invalid by specifying a transition to TPA$_FAIL at main level. 
LIB$TPARSE returns with the value LIB$_SYNTAXERR or an alternate 
failure status returned by an action routine. 

3 An error occurs at main level. The error can be either: 

• A syntax error. All transitions in the current state fail to match the 
current token. LIB$TPARSE returns LIB$_SYNTAXERR or an alternate 
failure status returned by an action routine. 

• A state table format error. One of your state table entries is invalid. 
LIB$TPARSE returns LIB$_INVTYPE. 

LIB$TPARSE generates no signals and establishes no condition handler- 
action routines can signal through LIB$TPARSE back to the calling program. 

The sections that follow describe each of these parts in more detail. 

The Alphabet of LIB$TPARSE 

LIB$TPARSE recognizes strings made up of elements of the ASCII character 
set. It provides all the basic building blocks needed for constructing a 
grammar using the ASCII character set. There are also symbols that represent 
the more complex constructions found in programming and command 
language grammar. 

Table RTL-16 illustrates the alphabet of LIB$TPARSE. 


Table RTL-16 The Alphabet of LIB$TPARSE 


Symbol 

V 


TPA$_ANY 

TPA$_ALPHA 

TPA$_DIGIT 


Character Matched 

The particular ASCII character. In a state table, it is expressed 
by enclosing the character in single quotation marks. The 
character can be any member of the 8-bit ASCII code set. 
LIBSTPARSE does not consider uppercase and lowercase 
alphabetic characters and codes with different values in bit 7 
to be equivalent. 

Any single character. (The actual matching character is placed 
in the TPA$B_CHAR field of the argument block.) 

Any alphabetic character, which includes the DEC multinational 
character set. 

Any numeric character, that is, 0 through 9. 
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Table RTL-16 (Cont.) The Alphabet of LIB$TPARSE 

Symbol Character Matched 


TPA$_STRING 


TPA$_SYMBOL 


TPA$_BLANK 

TPA$_DECIMAL 


TPA$_OCTAL 


TPA$_HEX 


TPA$_FILESPEC 


TPA$_UIC 


TPAS—IDENT 


Any string of one or more alphanumeric characters, that 
is, uppercase or lowercase A through Z, and the numeric 
characters 0 through 9. The string can be any length. It is 
bounded on the right by the first nonalphanumeric character or 
by the end of the string. A descriptor of the matching string 
is available in the argument block. 

Any string of one or more characters of the standard VAX 
symbol constituent set, that is, uppercase and lowercase A 
through Z and all DEC multinational characters, in addition 
to the dollar sign ($), and the underscore (_). The string is 
bounded on the right by some character not in the symbol 
constituent set (usually a blank), or by the end of the string. 

Any string of one or more blanks and/or tabs. 

Any decimal number (that is, any string of one or more digits 
0 through 9) whose magnitude is less than 2 32 . The binary 
value of the number, converted in decimal radix, is placed in 
the argument block. 

Any octal number (that is, any string of one or more digits 
0 through 7) whose magnitude is less than 2 32 . The binary 
value of the number, converted in octal radix, is placed in the 
argument block. 

Any hexadecimal number (that is, any string of one or more 
digits 0 through 9, A through F) whose magnitude is less 
than 2 32 . The binary value of the number, converted in 
hexadecimal radix, is placed in the argument block. 

Any string of one or more characters that constitutes a valid 
VAX/VMS file specification. The string is bounded on the 
right by the first character that either is not a file specification 
constituent character or would cause the sring to violate the 
syntax rules of a file specification. 

Any string that constitutes a valid VAX/VMS numerical UIC 
specification, bounded by square brackets or angle brackets. 

The binary value of the UIC, converted in octal radix, is placed 
in the argument block. The wildcard character ( )* is permitted 
in the group and/or member fields; its presence results in that 
field being set to its largest possible value in the binary value. 

Any string that constitutes a valid VAX/VMS identifier. 

Identifiers may be given as numerical UlCs according to the 
rules for TPA$_UIC, or as alphabetic identifier names that 
appear in the system's rights database. The binary value of 
the identifier, converted in either octal or hexadecimal radix 
or by lookup in the system rights database, is placed in the 
argument block. Identifiers may be entered in any of the 
following forms: 

[n,m] <n,m> 

[namel,name2] enamel,name2> 

[name] <name> 

name 

%Xhex-value 

(any above instance oi number or name may also be *) 
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Table RTL-16 (Cont.) The Alphabet of LIB$TPARSE 


Symbol 

Character Matched 

'keyword' 

The string of characters enclosed in single quotation marks. 

A keyword can consist of one or more characters of the VAX 
symbol constituent set, that is, uppercase and lowercase A 
through Z, the numerals 0 through 9, the dollar sign ($), and 
the underscore (_). Uppercase and lowercase alphabetics 
are treated as different characters. A state table can contain 
up to 220 keywords. The keyword is bounded on the right 
by a character not in the symbol constituent set, or by the 
end of the string. Keywords that are one character in length 
are expressed in the form 'x*' to distinguish them from the 
single-character symbol (V). They must be differentiated 
since they are not the same in operation. 


For example, in the input string AB+C, the single character 
'A' would match the first character of this string, whereas the 
keyword 'A*' would not, since B in the string is in the symbol 
constituent set. 

TPA$_LAMBDA 

The empty string (always matches). As it executes the 
transition, LIBSTPARSE does not remove any characters 
from the input string. LAMBDA transitions are useful in 
getting action routines called under otherwise awkward 
circumstances, providing unconditional GOTOs to link portions 
of a state table together, and providing default actions in 
certain cases. 

TPA$_EOS 

The end of the input string. 

label 

A subexpression. LIBSTPARSE enters the state table at 
the indicated label and executes state transitions until a 
final state is entered. If the subexpression fails (that is, if 
it encounters a syntax error in the input string), the input 
string is backed up to the point at which the subroutine 
started, and the subexpression simply fails to match. The 
subexpression facility permits complex syntactic constructs 
that appear in many places in grammar to appear only once in 
the state table. It also permits a degree of nondeterministic 
or pushdown parsing with a parser that is otherwise 
deterministic and finite-state. See the section entitled "Using 
Subexpressions." 


A theoretical finite-state machine simultaneously compares the symbol types 
given by all of the transitions out of a particular state with the current 
token. The machine then executes the one transition whose symbol type 
matches. Since an ordinary sequential computer executes LIB$TPARSE, it 
evaluates the transitions sequentially and executes the first transition whose 
symbol type matches. Note also that the set of symbol types implemented 
by LIB$TPARSE matches overlapping sets of tokens. For example, the token 
123 could match TPA$_DECIMAL, TPA$_OCTAL, TPA$_STRING, or one 
of several other symbol types. 

Thus if there is more than one transition out of a state whose symbol types 
match overlapping sets of tokens, you must order the symbol types carefully. 
For example, the TPA$_SYMBOL symbol type matches all keyword strings. 
In general, LIB$TPARSE will never execute keyword transitions appearing in 
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a state following a TPA$_SYMBOL. It is best, therefore, to order transitions 
of different types in order of increasing generality, as follows: 

'keyword 7 

V 

TPA$_EOS 

TPA$_ALPHA 

TPA$_DIGIT 

TPA$_BLANK 

TPA$_OCTAL 

TPA$_DECIMAL 

TPA$_HEX 

TPA$_STRING 

TPA$_SYMBOL 

TPA$_UIC 

TPA$_IDENT 

TPA$_FILESPEC 

TPA$_ANY 

TPA$_LAMBDA 

Note that subexpressions are not in this list; their placement depends on the 
symbol types recognized within the subexpression. If you use action routines 
to reject certain transitions, you can change the order in which that symbol 
type is placed in this order. In any case, however, LIB$TPARSE will execute 
the first transition listed in a state that is permitted to match the leftmost 
portion of the input string. 

The LIB$TPARSE Argument Block 

LIB$TPARSE finds the input string through the argument block. This 
argument block is the impure data base upon which LIB$TPARSE operates. 
That is, it is a set of variable data that can be written as well as read. 

It contains information about the string to be parsed, option flags for 
LIB$TPARSE, and data about the current token. When LIB$TPARSE calls 
an action routine, the argument block becomes the argument list of the action 
routine, allowing efficient reference by the routine. 

The fields in the argument block have symbolic names. Assembly language 
programs can define these names by invoking the macro $TPADEF 
(automatically loaded from the system macro library). The field names define 
the byte offset of the field from the start of the argument block, with the 
exception of the bit fields ($V_names), which are defined as bit offsets from 
the start of the containing field. In addition, bit mask values ($M_names) are 
available for the bit fields. 

The same field names are available to BLISS programs from the system macro 
library SYS$LIBRARY:STARLET.L32. Each name (except for the $M_names) 
is defined as a fixed-reference macro that operates on a byte-based block. The 
$M—names are defined as literals. 

Table RTL-17 contains the fields of the argument block. 
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Table RTL-17 Argument Block Fields 

Symbol _ Meaning _ 

TPA$I_COUNT A longword containing the number of longwords that make up the rest of the 

argument block. This longword functions as the argument count when the 
argument block becomes the argument list to an action routine. This field 
must contain the value TPA$K_COUNTO (whose numeric value is 8). 


TPA$I_OPTIONS 


A longword containing various option and flag bits. The defined flags are as 
follows: 

TPA$V_BLANKS Setting this bit causes LIBSTPARSE to process 

blanks and tabs explicitly, rather than treating 
them as invisible separators (see the section 
entitled "Blanks in the Input String" on blank 
processing). 


TPA$V_ABBRFM Setting this bit allows keywords to be 

abbreviated to any length. If an abbreviated 
keyword string is ambiguous, the first eligible 
transition listed in the state matches it. 


TPA$V_ABBREV Setting this bit allows keywords to be 

abbreviated to the shortest length that is 
unambiguous in that state. (See the section 
entitled "Abbreviating Keywords" on keyword 
abbreviation.) 

TPA$V_AMBIG LIBSTPARSE sets this bit when it has detected 

an ambiguous keyword string in the current 
state. 


TPA$B_MCOUNT 


TPA$I_STRINGCNT 

TPA$I_STRINGPTR 


TPA$I_TOKENCNT 

TPA$I_TOKENPTR 


TPA$B_CHAR 


A byte containing the minimum number of characters in the abbreviation of 
a keyword. If zero, abbreviations are not allowed. Preventing ambiguity is 
the responsibility of the state table designer. If TPA$V_ABBRFM or TPA$V_ 
ABBREV is set, LIBSTPARSE ignores this value. 

A longword containing the number of characters remaining in the input string. 

A longword containing the address of the remainder of the string being 

parsed. Taken together, TPA$I_STRINGPTR and TPA$I_STRINGCNT form a 

descriptor for the input string. Your program initializes this descriptor with the 
string to be parsed. When LIBSTPARSE calls an action routine, this descriptor 
describes the remainder of the input string. When LIBSTPARSE returns, this 
descriptor describes the portion of the input string that LIBSTPARSE did not 
process. (This occurs whether LIBSTPARSE returns success or failure.) 

A longword containing the number of characters in the current token. 

A longword containing the address of the current token. Taken together, 

TPA$I_TOKENPTR and TPA$I_TOKENCNT form a descriptor for the current 

token. If LIBSTPARSE encounters a syntax error (fails to match a transition), 
then this descriptor describes whatever portion of the current input string 
would have been matched by a TPA$_SYMBOL symbol type. If none would 
have matched, it describes the first remaining character in the input string. A 
transition to TPA$_FAIL leaves the descriptor describing the token matched 
by that transition—that is, the string that failed. 

A byte containing the character matched by a single-character symbol type 
('x', TPA$_ANY, TPAS—ALPHA, or TPA$_DIGIT). The remainder of the 
longword is not used. 
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TPA$I_NUMBER 

A longword containing the binary value of a numeric token (TPA$_DECIMAL / 
TPA$_OCTAL, or TPA$_HEX), converted in the appropriate radix. 

TPA$I_PAR AM 

A longword containing the 32-bit argument supplied by the state transition. 

LIBSTPARSE modifies the three preceding fields (TPA$I_CHAR, TPA$I_ 

NUMBER, and TPA$I_PARAM) only when it is about to call an action routine 

from a transition of the relevant type (or containing an explicit argument). 
While LIBSTPARSE is executing transitions of unrelated types, it does not 
modify the fields. 

TPA$K_LENGTHO 

This symbol represents the number of bytes in the basic LIBSTPARSE 
argument block. You must pass an argument block of at least this length 

(containing a count field of TPA$K_COUNTO in TPA$I_COUNT) as the first 

argument to LIBSTPARSE. You may pass a longer block if you wish to pass 
extra context to action routines in a modular way. 


The names TPA$M_BLANKS, TPA$M_ABBRFM, TPA$M_ABBREV, and 

TPA$M_AMBIG define bitmasks that correspond to the location of the 
corresponding $V_ fields in the options longword. 

The State Tables 

This section describes the set of macros used to construct state tables. The 
section entitled "Coding and Using a Simple State Table" explains how to use 
these macros to construct a state table. 

The state table must be set up using either MACRO or BLISS. Everything 
else, including the action routines, can be coded in the language of your 
choice. Simply compile the state table separately, then link it with your 
program. 

MACRO State Table Generation Macro Calls 

The VAX/VMS system macro library contains a set of assembler macros that 
allow convenient and readable coding of a LIBSTPARSE state table. Macros 
exist to initialize the LIBSTPARSE macro system, define the states in the 
state table, and define the transitions to other states within each state. These 
macros generate symbol definitions and tables. They do not produce any 
executable code or routine calls. 

$INIT_STATE—Initialize the LIBSTPARSE Macros 

The $INIT_STATE macro declares the beginning of a state table. It initializes 
the internals of the table generator macros and declares the locations of the 
state table and the keyword table. The state table is the structure containing 
the definitions of the states and the transitions between them. The keyword 
table contains the text of the keywords used in the state table. 

$INIT_STATE state-table .key-table 

state-table 

The name assigned to the state table. LIBSTPARSE equates this label to the 
start of the first state in the state table. 

key-table 

The name assigned to the keyword table. LIBSTPARSE equates this label to 
the start of the keyword table. 
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You must supply both the address of the state table and the address of the 
keyword table in the call to LIB$TPARSE to perform a parse. The $INIT_ 
STATE macro can appear more than once in a program. Each occurrence 
defines a separate state table. No part of any state table can refer to part of 
any other state table. 

$ ST ATE—Defining a State 

The $STATE macro declares the beginning of a state. 

$STATE [label] 

label 

An optional label for the state. LIB$TPARSE equates the label, if present, to 
the starting address of the state. 

$TRAN—Defining State Transitions 

The $TRAN macro defines a transition from the state in which it appears to 
some other (or to the same) state. The arguments of the macro define, among 
other things, the symbol type that causes the transition to be executed, the 
state to which to transfer, and the action routine to call, if any. 

$TRAN type [.label] [.action] [.mask] [,msk-adr] [.argument] 

type 

The symbol type recognized by this transition. The transition is taken if the 
characters at the front of the input string match the symbol specified. The 
symbol can be any of the constructs discussed in the section entitled "The 
Alphabet of LIB$TPARSE." 

A subexpression symbol type has the syntax Ilabel. 

label 

The optional target state of this transition. If present, it must be the label 
assigned to some state in the state table. If no label is present in the 
transition, LIB$TPARSE transfers control to the next state immediately 
following in the state table. If the label is the expression TPA$_EXIT, the 
parsing operation in progress is terminated with a success status. If the label 
is the expression TPA$_FAIL, the parsing operation stops with a failure 
status, as if a syntax error had occurred. 

action 

The optional address of a user-supplied action routine. If this argument is 
present, LIB$TPARSE calls the named action routine before the transition is 
taken. The section entitled "Action Routines" describes the calling sequence 
of action routines and the information available to them. 

Since the action routine address is self-relative, it cannot be in a shared image 
separate from the state table. 

mask 

An optional 32-bit mask value used with the msk-adr argument. If the mask 
is present, LIB$TPARSE performs an inclusive OR operation using this value 
and the longword specified by msk-adr. Use of the mask argument allows 
the state table to flag the fact that a certain transition was taken without the 
expense and overhead of calling an action routine. 

msk-adr 

The optional address associated with the preceding mask argument. 
LIB$TPARSE performs the inclusive OR operation on this address and the 
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mask argument, and stores the result at the address. If the mask argument is 
present, the msk-adr argument must also be present. 

The msk-adr argument can also be present without the preceding mask 
argument. In this case, it specifies an address where the procedure stores 
information about the matching token. The information stored depends on 
the nature of the symbol, as follows: 

• If the symbol is a number (that is, if the type code in the transition is 
TPA$_DECIMAL, TPA$_OCTAL, or TPA$_HEX), the address contains 
the 32-bit binary value of the number (an unsigned longword). 

• If the symbol is a single character (that is, if the type code in the transition 
is V, TPA$_ANY, TPA$_ALPHA, or TPA$_DIGIT), the address (an 
unsigned byte) contains the 8-bit matching character. 

• If the symbol is of any other type, the address contains the 64-bit string 
descriptor of the matching token (an unsigned quadword; class and data 
type fields in the descriptor are undefined). 

Using msk-adr makes your program nonmodular. 

The use of the msk-adr alone lets a parser program extract the most 
commonly needed information from the input string without using action 
routines. Note that LIB$TPARSE stores the information, and does not 
perform an OR operation as it does if mask is present. 

Since the action routine address is self-relative, it cannot be in a shared image 
separate from the state table. 

argument 

An optional 32-bit value that LIB$TPARSE passes to the action routine 
without interpretation. This argument can be an identifier number, an 
address, or any other information your action routine needs. It allows a 
single action routine to serve many transitions for which similar, but slightly 
varying, actions must be performed. 

Using argument as an address is nonmodular. 

Note that the argument appears in the state table in its absolute form. 
Normally, LIB$TPARSE stores addresses as self-relative pointers; however, 
LIB$TPARSE does not know the form or meaning of argument, so it is 
stored in its absolute form. If argument is used as an address, therefore, the 
resulting parsing program containing this state table will not be position- 
independent code (PIC). 

$END_STATE—End the State Table 

The $END_STATE macro declares the end of the state table. It is mandatory, 
in order to permit the orderly cleanup of the LIB$TPARSE macro system. The 
$END_STATE macro has no arguments. You code it as follows: 

$END_STATE 

BLISS State Table Generation Macro Calls 

The file SYS$LIBRARY:TPAMAC.L32 contains a set of BLISS macros that 
allow convenient and readable coding of LIB$TPARSE state tables in 
BLISS. To make the macros available to the program, include the following 
declaration in the module containing the state tables: 

LIBRARY 'SYS$LIBRARY:TPAMAC; 
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BLISS requires only two macros: $INIT_STATE to initialize the macros and 
$STATE to define each state in its entirety. The syntax of the $INIT_STATE 
and $STATE macros are defined below. 

$INIT_STATE—Initialize the LIB$TPARSE Macros 

The $INIT_STATE macro initializes the LIB$TPARSE macro system in the 
same manner as it does for the assembler. 

$INIT_STATE (state-table, key-table); 

state-table 

The name assigned to the state table. LIB$TPARSE equates this label to the 
start of the first state in the state table. 

key-table 

The name assigned to the keyword table. LIB$TPARSE equates this label to 
the start of the keyword table. 

Both names are declared as global vectors of length zero. As with the 
assembler macros, you can invoke $INIT_STATE more than once to declare 
several state tables within a single module. 

$STATE—Declaring a state and its transitions 

In BLISS, you use the $STATE macro to declare a state in its entirety. 

$STATE ([label], 

( transition ), 

( transition ), 

( transition ) 


); 


label 

Optional address of the start of the state. The compiler declares label as a 
local vector of length zero. Note that the comma following the optional label 
is mandatory. 

transition 

Each transition appears within the parentheses in the same form as the 
transition argument list for the assembler $TRAN macro. 

type [,label] faction] [,mask] [,msk-adr] [,argument] 

The arguments of each transition are expressed in exactly the same format 
as in the assembler macros, with the exception of the subexpression type. In 
BLISS, this type has the form (label). 

Note that the transitions are not keyword macros. Therefore, you must use 
commas to indicate arguments you have skipped. 

The BLISS table generation macros contain no BEGIN or END statements. 
This allows $STATE macros to refer to each other. They generate all 
storage with OWN declarations. This means that the macros modify PSECT 
declarations for OWN and GLOBAL storage. Thus if other data declarations 
follow the state table declarations, they may not have the correct attributes. 
You cannot simply surround the state table with BEGIN/END, because this 
constitutes an expression. No declarations of any kind, including ROUTINE 
declarations, can follow an expression. 
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There are four techniques for including LIB$TPARSE state tables in BLISS 
modules. 

1 Follow the state table with explicit redeclarations of the OWN and 
GLOBAL PSECTs. The BLISS example in the "Examples" section uses this 
technique. 

2 Place the state table in a separate module. The high-level language 
examples in the next section use this technique. 

3 Place the state table between BEGIN and END statements after the 
declarations within a routine body. 

4 Place the state table between BEGIN and END statements at the end of a 
module. 

In all cases, of course, you must define all action routines, masks, addresses, 
and arguments with suitable declarations (which can be FORWARD or 
EXTERNAL). The LIB$TPARSE macros handle the necessary FORWARD 
declarations for forward references to labels within the state table. 

Coding and Using a Simple State Table 

LIB$TPARSE can be used to parse programming languages, command 
languages, or any other grammar for which a deterministic parser is the best 
choice. The following sections show how to use it to parse the command 
language of a simple report management utility. 

This hypothetical utility allows a user to perform the following activities: 

1 Obtain a list of available reports (SHOW command). 

2 Read reports on the terminal (READ command). 

3 Print reports (PRINT command). 

4 Store new reports (FILE command). 

The examples use the BASIC programming language for everything except 
the state and keyword tables, which are coded in BLISS. 

Coding a parser program using LIB$TPARSE involves three steps: 

1 Set up state tables to implement your language's grammar. 

2 Define the argument block and other common variables. 

3 Code the main program, including the call to LIB$TPARSE. 

This simple state table program does not use any action routines or other 
arguments. See the section entitled "Using Advanced LIB$TPARSE Features" 
for information about how to use these features of LIB$TPARSE. 

Setting up the State Tables 

A state table associates the parser's alphabet with a set of possible transitions. 
You begin the state table with an $INIT_STATE macro and define the states 
and transitions using the $STATE and $TRAN macros. 

One easy way to set up these tables is to start from a transition diagram of 
the language you want to parse. (If you do not know how to construct a 
transition diagram, you might find it helpful to read a good introductory text 
about compiler design and construction before you start.) Each circle in the 
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diagram becomes a $STATE macro, and each arrow representing a transition 
out of that state becomes a $TRAN macro. 


Figure RTL-7 illustrates a transition diagram for the mythical utility described 
in "Setting up the State Tables". 

Figure RTL-7 Transition Diagram for the Mythical Utility 



The state table for this simple language looks like this: 

.TITLE 8implelang 
.ident 'vl' 


SIMPLE.KEYWORD.TABLE 


$TRAN 'PRINT' 
$TRAN 'READ', 
$TRAN 'FILE', 
ITRAN 'SHOW', 


Define the TPARSE control symbols 
$TPADEF 

$INIT_STATE SIMPLE.LANGUAGE.TABLE, 

$STATE START 

. NEED.REPORT 
NEED.REPORT 
NEED.REPORT 
NEED.REPORT 

$STATE NEED.REPORT 

$TRAN TPA$_SYMBOL, NEED.REPORT 

$TRAN TPAI.EOS, TPA$_EXIT 

$END_STATE 

.END 

Another technique for developing a state table starts with a tabular diagram 
in which the first column is the starting state, the second column identifies 
the input token, and the third gives the resultant state. 

Figure RTL-8 is a diagram of the same mythical utility that appeared 
in RTL-7. 
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Figure RTL-8 Diagram of the Mythical Utility 


Starting state 

Input 

Resulting state 


PRINT 

need-report-name 


READ 

need-report-name 

___ __ ——— 

FILE 

need-report-name 


SHOW 

need-report-name 

need-report-name 

report name 

done 

need-report-name 

end of string 

done 

need-report-name 

other 

error 


ZK-1980-84 


In this case, each block of entries becomes a $STATE macro and each option 
within that block is a possible transition to the next state. Using the BLISS 
macros yields the following state table definition. 

MODULE simple_statetable = 

BEGIN 
! + 

! These libraries contain the macros and other definitions 
! needed to generate the state tables, 
j - 

LIBRARY 'SYS$LIBRARY:STARLET'; 

LIBRARY 'SYSILIBRARY:TPAMAC'; 

! + 

! UFD_STATE is the name you are giving the state table. 

! UFD.KEY names the keyword table. 

! Be sure to use the same name in the call to LIB$TPARSE. 

j - 

SINIT.STATE (UFD.STATE, UFD_KEY); 

! + 

! Read the command name (to the first blank in the command). 

! Each string is a keyword; you are limited to 220 keywords 
! per state table. 

i - 

$STATE (START, 

('CREATE'), 

('FILE'), 

('PRINT'), 

('READ') 

); 

ISTATE (LOOP, 

(TPAl.STRING, LOOP), ! If there is more than one report name 
! specified, go back and process it. 

(TPAI.EOS, TPA$_EXIT) ! exit when done. 

); 

END 

ELUDOM ! End of module CREATE.TABLE 

Assemble or compile this module as you would any other program module. 


Be careful of your punctuation here. 
Each transition is surrounded by 
parentheses; each entry except the 
last is followed by a comma. 
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Defining the Argument Block 

After you have set up the state tables, you need to declare the LIB$TPARSE 
argument block in such a way that both your program and LIB$TPARSE can 
use it. This means the data must be defined in an area common to the calling 
program and the program module containing the state table definitions. 

In most programming languages you will use a combination of EXTERNAL 
statements and common data definitions to create and access a separate data 
PSECT. If you do not know what mechanisms the language you are using 
provides, consult the documentation for that language. 

The following example shows the LIB$TPARSE argument block defined for 
use in a BASIC program. 

!LIB$TPARSE requires that TPA$K_COUNTO be eight. 

DECLARE INTEGER CONSTANT TPA$K_COUNTO =8. k 


BTPA$L_COUNT =0. k 

BTPA$L_0PTI0NS=1, k 

BTPA$L_STRINGCNT=2. k 

BTPA$L_STRINGPTR=3. k 

BTPA$L_T0KENCNT=4. k 

BTPA$L_T0KENPTR=5. k 

BTPA$B_CHAR=6. k 

BTPA$L_NUMBER=7. k 

BTPA$L_PARAM=8 

! + 

! The LIB$TPARSE argument block. 


MAP (TPARSE_BL0CK) LONG TPARSE.ARRAY (TPA$K_C0UNT0) 

! + 

! Redefining the map allows you to use the standard 
! LIB$TPARSE symbolic names. TPA$L_STRINGCNT, 

! for example, references the same storage location 
! as TPARSE.ARRAY(2) and TPARSE.ARRAY(BTPA$L_STRINGCNT). 

i - 


MAP (TPARSE.BLOCK) LONG k 

TPA$L_C0UNT , k 

TPA$L_0PTI0NS, k 

TPA$L_STRINGCNT, k 

TPA$L_STRINGPTR, k 

TPA$L_TOKENCNT, k 

TPA$L_TOKENPTR, k 

TPA$B_CHAR, k 

TPAIL.NUMBER, k 

TPA$L_PARAM 


Coding the Call to LIB$TPARSE 

Before your program can call LIB$TPARSE, it must place the necessary 
information in the argument block. Since this utility uses all the LIB$TPARSE 
defaults for blanks processing, abbreviations, and so on, it does not need to 
set any flags. It must, however, put the address and length of the string to be 
parsed into the TPA$L_STRINGCNT and TPA$L_STRINGPTR fields. 

This information is available in the descriptor of the input string (called 
COMMAND_LINE in this program). However, BASIC, like most high-level 
languages, does not allow you to look at the descriptors of your strings. 
Instead, you can use LIB$ANALYZE_SDESC to read the length and address 
from the string descriptor and place them in the argument block. (See line 
75.) 
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Note that this program uses the BLISS state table described in the section 
entitled "Setting Up the State Tables." 

5 %TITLE "Program to demonstrate using LIB$TPARSE from a high-level language" 

OPTION TYPE=EXPLICIT 
! + 

! COMMAND.LINE is the string to receive the input 
• command from the terminal. 

! ERROR_MSG_TEXT is the system error message 
! returned from LIB$SYS_GETMSG 
! (used in the error handling routine) 

DECLARE STRING COMMAND_LINE, ERROR_MSG_TEXT 
! + 

! RET.STATUS receives the status from the system calls. 

! SAVE.STATUS is used when an error occurs 
! and the error handling routine calls 
! LIB$SYS_GETMSG to obtain the error text. 

DECLARE LONG RET.STATUS, SAVE_STATUS 
! + 

! UFD.STATE is the address of the state table. 

! UFDJCEY is the address of the key table. 

! Both addresses are set up by the macros in module 
! SIMPLE.STATETABLE32. 

; - 

EXTERNAL LONG UFD.STATE, UFD.KEY 
! + 

! To allow us to compare returned statuses more easily. 

EXTERNAL INTEGER CONSTANT SSl.NORMAL, A 
LIB$_SYNTAXERR, A 

LIB$_INVTYPE 

! ♦ 

! This program calls the following Run-Time Library 
! routines: 

! 

! LIB$TPARSE to parse the input string 

i 

! LIB$ANALYZE_SDESC to get the length and starting 
! address of the command string and place them 
! in the LIB$TPARSE argument block. 

! 

! LIB$SYS_GETMSG to find the facility, severity, and text 
! of any system errors that occur 

! during program execution. 

EXTERNAL LONG FUNCTION LIBlTPARSE, A 

LIB$ANALYZE_SDESC, A 
LIBSSYS.GETMSG 


20 


50 


! ♦ 

! This file defines the argument block that is passed 
! to LIB$TPARSE. It also defines subscripts that 
! make it easier to access the array. 

i 

! Keeping the argument block definitions in a separate 
! file makes them easier to modify and lets other 
! programs use the same definitions. 

•/.INCLUDE "SIMPLE.TPARSE.BLOCK" 

ON ERROR GOTO ERROR.HANDLER 
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60 


LIBITPARSE requires that TPA$L_C0UNT, the 
first field in the argument block, have a value 
of TPA$K_COUNTO, whose value is 8. 


TPA$L_C0UNT = TPAIK.C0UNT0 
75 ! + 

! Prompt at the terminal for the user's action. 

! A real utility should provide a friendlier, 

! clearer interface. 

j - 

GET.INPUT: PRINT "Your options are: " , " READ report " 

PRINT . - FILE report - 
PRINT , " PRINT report " 

PRINT , " CREATE report " 

PRINT 

INPUT "What would you like to do"; COMMAND.LINE 

! + 

! Get the length and starting address of the command line 
! and place them in the LIB$TPARSE argument block. Note 
! that LIB$ANALYZE_SDESC stores the length as a word. 

j - 

RET.STATUS * LIB$ANALYZE_SDESC (COMMAND.LINE BY DESC, & 
TPARSE.ARRAY (BTPA$L_STRINGCNT) BY REF, & 

TPARSE.ARRAY (BTPA$L_STRINGPTR) BY REF) 

IF RET.STATUS <> SS$_N0RMAL THEN 

GOTO ERROR.HANDLER 

END IF 
100 ! + 

! Call LIB$TPARSE to process the input string. 

! Note that LIB$TPARSE expects to receive its arguments 
! by reference, while BASIC's default for arrays and 
! strings is by descriptor. Therefore the BY REF 
! clauses are required. Without them, LIB$TPARSE 
! cannot find the input string 
! and the parse will always fail. 

i - 

RET.STATUS = LIBITPARSE (TPARSE.ARRAY () BY REF, k 
UFD.STATE BY REF, k 

UFD.KEY BY REF ) 

! + 

! This simple program provides no information except that 
! a valid command was entered. The next section discusses 
! techniques for gathering more information. 


IF RET.STATUS = SSl.NORMAL 
! + 

! For now, exit on success, 
j - 

THEN PRINT "Parse successful" 

GOTO 9999 

• + 

! If the parse failed, give the user a chance to try again. 

ELSE IF RET.STATUS = LIBl.SYNTAXERR THEN 

PRINT "You did not enter a valid command." 
PRINT "Please try again." 

GOTO GET.INPUT 
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! + 

! If a more serious error occured, inform the user 
! and exit. 

! - 

ELSE 

Goto ERROR.HANDLER 

END IF 

END IF 

500 ERROR.HANDLER: SAVE.STATUS = RET.STATUS 

RET.STATUS = LIB$SYS_GETMSG (SAVE.STATUS,.ERROR.MSG.TEXT) 

PRINT "Something went wrong." 

PRINT ERL, ERROR.MSG.TEXT 
RESUME 9999 

9999 END 

Compile this program as you would any other BASIC program. 

When both the state tables and the main program have been compiled, link 
them together to form a single executable image, as follows: 

$ LINK SIMPLANG,SIMPLANG.STATETABLE 

Using Advanced LIB$TPARSE Features 

The simple LIB$TPARSE call in the previous program tells you that the 
command the user entered was valid, but nothing else—not even which 
command was entered. Most of the time your program will need more 
information than this. 

The following sections describe some of the more complicated techniques you 
can use to gather extra information for your program. 

Action Routines 

When the transition being matched specifies an action routine to be called, 
LIB$TPARSE stores the optional argument longword, if it is present, in the 
argument block and calls the action routine. If the action routine returns 
failure, LIB$TPARSE continues attempting to match successive transitions. If 
the action routine returns success, LIB$TPARSE executes the transition as it 
would if there was no action routine present. It stores the mask or other value 
at the mask address, if specified, and passes control to the specified target 
state. If no target state is given, control passes to the next state following in 
the state table. In either case, LIB$TPARSE does not evaluate the remaining 
transitions in the state. 

LIB$TPARSE calls action routines with a CALLG instruction. When a state 
transition specifies an action routine, LIB$TPARSE calls the action routine 
when the transition is found to be able to execute successfully (that is, when 
its symbol type matches a leading portion of the input string). It calls the 
action routine before processing the mask or msk-adr arguments of the state 
transition. 

The argument list for the action routine is the LIB$TPARSE argument block. 
Thus an action routine written in assembly language, for example, can 
reference fields in the argument block by their symbolic offsets relative to the 
AP (Argument Pointer) register. 

The action routine returns a value to LIB$TPARSE in RO that controls 
execution of the current state transition. If the action routine returns success 
(low bit set in RO) then LIB$TPARSE proceeds with the execution of the 
state transition. If the action routine returns failure (low bit clear in RO), 
LIB$TPARSE rejects the transition that was being processed and acts as if the 
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symbol type of that transition had not matched. It proceeds to evaluate other 
transitions in that state for eligibility. 

If an action routine returns a nonzero failure status to LIB$TPARSE and 
no subsequent transitions in that state match, LIB$TPARSE will return the 
status of the action routine, rather than the status LIB$_SYNTAXERR. In 
longword-valued functions in high-level languages, this value is returned in 
RO. 

Allowing action routines to reject a state transition allows you to implement 
symbol types specific to particular applications. To recognize a specialized 
symbol type, code a state transition using a LIB$TPARSE symbol type that 
describes a superset of the desired set of possible tokens. The associated 
action routine then performs the additional discrimination necessary and 
returns success or failure to LIB$TPARSE, which then accordingly executes or 
fails to execute the transition. 

A pure finite-state machine, for instance, has difficulty recognizing strings that 
are shorter than some maximum length, or accepting numeric values confined 
to some particular range. 

Blanks in the Input String 

The default mode of operation in LIB$TPARSE is to treat blanks as invisible 
separators. That is, they can appear between any two tokens in the string 
being parsed without being called for by transitions in the state table. Since 
blanks are significant in some situations, LIB$TPARSE processes blanks if you 
have set the bit TPA$V_BLANKS in the options longword of the argument 
block. The following input string illustrates the difference in operation: 

ABC DEF 

LIB$TPARSE recognizes the string by the following sequences of state 
transitions, depending on the state of the blanks control flag. 

TPA$V_BLANKS set: 

ISTATE 

$TRAN TPA$_STRING 
ISTATE 

ITRAN TPA$_BLANK 
$STATE 

$TRAN TPA$_STRING 

TPA$V_BLANKS clear: 

ISTATE 

ITRAN TPAI.STRING 
ISTATE 

ITRAN TPAI.STRING 

Your action routines can set or clear TPA$V_BLANKS as LIB$TPARSE 
enters or leaves sections of the state table in which blanks are significant. 
LIB$TPARSE always checks the blanks control flag as it enters a state. If the 
flag is clear, it removes any space or tab characters present at the front of 
the input string before it proceeds to evaluate transitions. Note that when 
the TPA$V_BLANKS flag is clear, the TPA$_BLANK symbol type will never 
match. If TPA$V_BLANKS is set, you must explicitly process blanks. 
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Special Characters in the Input String 

Not all members of the ASCII character set can be entered directly in the state 
table definitions. Examples include the single quotation mark and all control 
characters. 

In MACRO state tables, such characters can be specified as the symbol type 
with any assembler expression that is equivalent to the ASCII code of the 
desired character, not including the single quotes. For example, you could 
code a transition to match a backspace character as follows: 

BACKSPACE = 8 


$TRAN BACKSPACE, . 

MACRO places extra restrictions on the use of a comma in arguments to 
macros; often they must be surrounded by one or more angle brackets. Using 
a symbolic name for the comma will avoid such difficulties. 

To build a transition matching such a single character in a BLISS state table, 
you can use the %CHAR lexical function as follows: 

LITERAL BACKSPACE = 8; 


ISTATE (label, 

(y.CHAR (BACKSPACE).) 

); 

Abbreviating Keywords 

The default mode of LIB$TPARSE is exact match. All keywords in the input 
string must exactly match their spelling, length and case in the state table. 
However, many languages (command languages in particular) allow you to 
abbreviate keywords. For this reason, LIB$TPARSE has three abbreviation 
facilities to permit the recognition of abbreviated keywords when the state 
table lists only the full spellings. 

• By setting a value in TPA$B_MCOUNT in the LIB$TPARSE argument 
block, the calling program or action routine specifies a minimum number 
of characters from the abbreviated keyword that must be present for a 
match to occur. For example, setting the byte to the value 4 would allow 
the keyword DEASSIGN to appear in an input string as DEAS, DEASS, 
DEASSI, DEASSIG, or DEASSIGN. 

LIB$TPARSE checks all the characters of the keyword string. Incorrect 
spellings beyond the minimum abbreviation are not permitted. 

• If TPA$V_ABBRFM is set in the options longword, LIB$TPARSE will 
recognize any leftmost substring of a keyword as a match for that 
keyword. LIB$TPARSE does not check for ambiguity; it matches the 
first keyword listed in the state table of which the input token is a subset. 

• If TPA$V_ABBREV is set in the options longword, LIB$TPARSE will 
recognize any abbreviation of a keyword as long as it is unambiguous 
among the keywords in that state. If LIB$TPARSE finds that the front 
of the input string contains an ambiguous keyword string, it sets the bit 
TPA$V_AMBIG in the options longword and refuses to recognize any 
keyword transitions in that state. (It still accepts other symbol types.) The 
TPA$V_AMBIG flag can be checked by an action routine that is called 
when coming out of that state, or by the calling program if LIB$TPARSE 
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returns with a syntax error status. LIB$TPARSE clears the flag when it 
enters the next state. 

For proper recognition of ambiguous keywords, the keywords in each state 
must be arranged in alphabetical order by the ASCII collating sequence, 
which is as follows: 

1 Dollar sign ($) 

2 Numerics 

3 Uppercase alphabetics 

4 Underscore (_) 

5 Lowercase alphabetics 

Be careful when using these options, since permitting short abbreviations 
restricts the extensibility of a language. Often, adding a new keyword can 
make a formerly valid abbreviation ambiguous. 

If both TPA$V_ABBRFM and TPA$V_ABBREV are set, TPA$V_ABBRFM 
takes precedence. 

Using Subexpressions 

LIB$TPARSE subexpressions are analogous to subroutines within the state 
table. A subexpression call, indicated with the MACRO expression !label or 
the BLISS expression (label), causes LIB$TPARSE to call itself recursively, 
using the same argument block and keyword table, and the specified label 
as a starting state. LIB$TPARSE processes the state transitions, consuming 
the portion of the input string called for. When LIB$TPARSE executes a 
transition to TPA$_EXIT, it returns success to itself. LIB$TPARSE thus 
considers the subexpression call a match, calls the action routine, and executes 
the transition. If the parse of the subexpression fails, LIB$TPARSE returns 
the portion that it consumed during the failed parse to the input string, and 
evaluates the remaining transitions in the state. 

You can use subexpressions as you would use subroutines in any program: 
to avoid replication of complex expressions. Subexpressions can also be used 
for a limited form of pushdown parsing, in which the state table contains 
recursively nested subexpressions. Finally, you can use subexpressions for 
nondeterministic parsing, that is, parsing in which you need some number of 
states of look-ahead. To do this, place each path of look-ahead in a separate 
subexpression and call the subexpressions in the transitions of the state that 
needs the look-ahead. When a look-ahead path fails, the subexpression 
failure mechanism causes LIB$TPARSE to back out and try another path. 

You should be careful when designing subexpressions that contain calls 
to action routines or use the mask and msk-adr transition arguments. 

As LIB$TPARSE processes state transitions of a subexpression, it calls 
the specified action routines and stores the mask and msk-adr. If the 
subexpression fails, LIB$TPARSE will back up the input string and resume 
processing in the calling state. However, any effects that the action routines 
have had on the caller's data base cannot be undone. If subexpressions are 
simply being used as state table subroutines, there is usually no harm done, 
since when a subexpression fails in this mode, the parse will generally fail. 
This is not true of pushdown or nondeterministic parsing. In applications 
where you expect subexpressions to fail, design action routines to store results 
in temporary storage. You can then make these results permanent at the main 
level, where the flow of control is deterministic. 


RTL-343 


Run-Time Library Routines 

LIB$TPARSE 


Using Subexpressions to Reject Transitions 

The following example is an excerpt of a state table that parses a string quoted 
by an arbitrary character. The table interprets the first character to appear as 
a quote character. Many text editors and some programming languages 
contain this sort of construction. Executing this set of state transitions leaves 
a descriptor for the string in the two longwords at Q_DESCRIPTOR, and the 
quoting character at location Q_CHAR. 


Main level state table. The first transition accepts and 
stores the quoting character. 

$STATE STRING 

$TRAN TPA$_ANY....Q.CHAR 

Call the subexpression to accept the quoted string and store 
the string descriptor. Note that the descriptor spans all 
the characters accepted by the subexpression. 

$STATE 

$TRAN !Q.STRING....Q.DESCRIPTOR 

Accept the trailing quote character, left behind by the 
subexpression 

ISTATE 

$TRAN TPA$_ANY,NEXT 


Subexpression to scan the quoted string. The first transition 
matches until it is rejected by the action routine. 


ISTATE Q.STRING 

$TRAN TPAI.ANY,Q.STRING,TEST.Q 

$TRAN TPAI.LAMBDA,TPAI.EXIT 


; The following MACRO subroutine compares the current character 
; with the quoting character and returns failure if it matches. 

TEST.Q: .WORD 
CMPB 
BNEQ 
CLRL 

10$: RET 

Using Subexpressions to Parse Complex Grammars 

The following example is an excerpt from a state table that shows how to 
use subexpressions to parse complex grammars. The state table accepts a 
number followed by a keyword qualifier. Depending on the keyword, the 
table interprets the number as decimal, octal, or hexadecimal. The state table 
will accept strings such as the following: 

10/OCTAL 

32768/DECIMAL 

77AF/HEX 


0 ; null entry mask 

TPA$B_CHAR(AP).Q.CHAR ; check the character 

10$ ; note RO is already 1 

RO ; match - reject transition 


This sort of grammar is difficult to parse with a deterministic finite-state 
machine. Using a subexpression look-ahead of two states permits a simpler 
expression of the state tables. 
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; Main state table entry. Accept a number of some type and store 
; its value at the location NUMBER. 

$STATE 

$TRAN !OCT.NUM,NEXT,,,NUMBER 

$TRAN !DEC.NUM,NEXT,,,NUMBER 

$TRAN !HEX.NUM,NEXT,,,NUMBER 

; + 

; Subexpressions to accept an octal number followed by the OCTAL 
; qualifier. 

$STATE OCT.NUM 

$TRAN TPA$.OCTAL 

$STATE 

$TRAN '/' 

$STATE 

$TRAN 'OCTAL',TPA$_EXIT 

; + 

; Subexpression to accept a decimal number followed by the DECIMAL 
; qualifier. 

$STATE DEC.NUM 

$TRAN TPA$.DECIMAL 

$STATE 

$TRAN '/' 

$STATE 

ITRAN ’DECIMAL',TPA$_EXIT 

; + 

; Subexpression to accept a hex number followed by the HEX 
; qualifier. 

$STATE HEX.NUM 

$TRAN TPA$_HEX 

$STATE 

$TRAN '/' 

ISTATE 

$TRAN 'HEX',TPA$.EXIT 

Note that the transitions following the numeric token do not disturb the 
TPA$_NUMBER longword, allowing the main level subexpression call to 
retrieve it. 

LIB$TPARSE and Modularity 

To use LIBSTPARSE in a modular and shareable fashion, make sure you 
avoid using OWN storage. Instead, allocate the argument block on the stack 
or the heap. 

Do not use the mask-adr argument at all. Do not use the argument argument 
as an address. 

If additional context is needed, allocate it at the end of the argument block. 

You will need to use action routines to control flags such as TPA$V_BLANKS. 
The MACRO example in the Examples section illustrates such an action 
routine, though the program itself is not modular. 

State Table Object Representation 

This section describes the binary representation of a LIB$TPARSE state table. 

Each state consists of its transitions concatenated in memory. LIB$TPARSE 
equates the state label to the address of the first byte of the first transition. A 
marker in the last transition identifies the end of the state. The LIB$TPARSE 
table macros build the state table in the PSECT _LIB$STATE$. 
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Each transition in a state consists of from 2 to 23 bytes containing the 
arguments of the transition. The state table generation macros do not allocate 
storage for arguments not specified in the transition macro. This allows 
simple transitions to be represented efficiently. For example, the following 
transition, which simply accepts the character '?' and falls through to the next 
state, is represented in two bytes: 

$TRAN '?' 

In this section, pointers described as self-relative are signed displacements 
from the address following the end of the pointer (this is identical to branch 
displacements in the VAX instruction set). 

A state transition consists of the following elements: 

• Symbol Type—One Byte 

The first byte of a transition contains the binary coding of the symbol type 
accepted by this transition. It is always present. Flag bit 0 in the flags 
byte controls the interpretation of the type byte. If the flag is clear, then 
the type byte represents a single character (the V construct). If the flag bit 
is set, then the type byte is one of the other type codes (keyword, number, 
and so forth). The symbol types accepted by LIB$TPARSE are encoded as 
follows: 


Symbol Type 

Binary Encoding 

'x' 

ASCII code of the character (8 bits) 

'keyword' 

The keyword index (0 up to 219) 

TPA$_FILESPEC 

234 

TPA$_UIC 

235 

TPA$_IDENT 

236 

TPA$_ANY 

237 

TPA$_ALPHA 

238 

TPA$_DIGIT 

239 

TPA$_STRING 

240 

TPA$_SYMBOL 

241 

TPA$_BLANK 

242 

TPA$_DECIMAL 

243 

TPA$_OCTAL 

244 

TPA$_HEX 

245 

TPA$_LAMBDA 

246 

TPA$_EOS 

247 

TPA$_SUBEXPR 

248 (subexpression call) 

(Other codes are reserved for expansion) 


Note: Use of the symbol types TPA$_FILESPEC and TPA$__IDENT 

will result in calls to the VMS system services $FILESCAN and 
$ASCTOID, respectively. If your application of LIB$TPARSE runs 
in an environment other than VMS user mode, you must carefully 
evaluate whether use of these services is consistent with your 
environment. 
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• First Flags Byte—One Byte 

This byte contains the following bits, which specify the options of the 
transition. It is always present. 

Bit 0 Set if the type byte is not a single character 
Bit 1 Set if the second flags byte is present 

Bit 2 Set if this is the last transition in the state 

Bit 3 Set if a subexpression pointer is present 

Bit 4 Set if an explicit target state is present 

Bit 5 Set if the mask longword is present 

Bit 6 Set if the msk-adr longword is present 

Bit 7 Set if an action routine address is present 

• Second Flags Byte—One Byte 

This byte is present if any of its flag bits is set. It contains an additional 
flag describing the transition. It is used as follows: 

Bit 0 Set if the action routine argument is present 

• Subexpression Pointer—Two Bytes 

This word is present in transitions that are subexpression calls. It is a 
16-bit signed self-relative pointer to the starting state of the subexpression. 

• Argument Longword—Four Bytes 

This longword contains the 32-bit action routine argument, when 
specified. 

• Action Routine Address—Four Bytes 

This longword contains a self-relative pointer to the action routine, when 
specified. 

• Bit Mask—Four Bytes 

This longword contains the mask argument, when specified. 

• Mask Address—Four Bytes 

This longword, when specified, contains a self-relative pointer through 
which the mask, or data that depends on the symbol type, is to be stored. 
Because the pointer is self-relative, when it points to an absolute location, 
the state table is not PIC (position-independent code). 

• Transition Target—Two Bytes 

This word, when specified, contains the address of the target state of the 
transition. The address is stored as a 16-bit signed self-relative pointer. 
The final state TPA$_EXIT is coded as a word whose value is -1; the 
failure state TPA$_FAIL is coded as a word whose value is -2. 

• Keyword Table 

This table is the structure to which the $INIT_STATE macro equates its 
second argument. The table is a vector of 16-bit signed pointers which 
address locations in the keyword string area, relative to the start of 
the keyword vector. As the state table source generates keywords, the 
LIB$TPARSE macros assign an index number to each keyword. The index 
number is stored in the symbol type byte in the transition; it locates the 
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associated keyword vector entry. The keyword strings are stored in the 
order encountered in the state table. Each keyword string is terminated by 
a byte containing the value -1. Between the keywords of adjacent states is 
an additional -1 byte to stop the ambiguous keyword scan. 

To ensure that the keyword vector is adjacent to the keyword string area, 
the keyword vector is located in PSECT _LIB$KEY0$ and the keyword 
strings and stored in PSECT _LIB$KEY1$. 

Your program should not use any of the three PSECTs used by 
LIB$TPARSE (_LIB$STATE$, _LIB$KEY0$, and _LIB$KEY1$). The 
PSECTs _LIB$KEY0$ and _LIB$KEY1$ refer to each other using 16- 
bit displacements, so user PSECTs inserted between them can cause 
truncation errors from the linker. 


CONDITION SS$_NORMAL 

VALUES 

LIB$_SYNT AXERR 


LIB$_INVTYPE 

Other 


Procedure successfully completed. LIBSTPARSE 
has executed a transition to TPA$_EXIT at main 
level, not within a subexpression. 

Parse completed with syntax error. LIBSTPARSE 
has encountered a state at main level in which none 
of the transitions match the input string, or in which 
a transition to TPA$_FAIL was executed. 

State table error. LIBSTPARSE has encountered an 
invalid entry in the state table. 

If an action routine returns a failure status other 
than zero, and the parse consequently fails, 
LIBSTPARSE returns the status returned by the 
action routine. 


EXAMPLES 

□ MODULE CREATE.DIR ( ! Create directory file 

IDENT = 'X0000', 

MAIN = CREATE_DIR) = 

BEGIN 


This BLISS program accepts and parses the command line 
of a CREATE/DIRECTORY command. Note that this is not in fact 
from the VAX CREATE/DIRECTORY utility ! It is a hypothetical 
example program. This program uses the LIB$GET_FOREIGN call 
to acquire the command line from the CLI and parse it with 
LIB$TPARSE, leaving the necessary information in its global data 
base. The command line is of the following format: 

CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

/UIC= [2437.25] 

/ENTRIES=100 

/PROTECTION=(SYSTEM:R.OWNER:RWED.GROUP:R.WORLD:R) 

The three qualifiers are optional. Alternatively, the command 
may take the form 

CREATE/DIR DEVICE: [202,31] 
using any of the optional qualifiers. 


Global data, control blocks, etc. 
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LIBRARY 'SYSILIBRARY:STARLET'; 

LIBRARY 'SYSILIBRARY:TPAMAC.L32'; 

• + 

! Macro to make the TPARSE control block addressable as a block 
! through the argument pointer. 

MACRO 

TPARSE_ARGS * 

BUILTIN AP; 

MAP AP : REF BLOCK [,BYTE]; 

•/.; 

! + 

! Declare routines in this module. 

i - 

FORWARD ROUTINE 

CREATE.DIR, 

BLANKS.OFF. 

CHECK_UIC, 

STORE.NAME, 

MAKE.UIC; 

! + 

! Define parser flag bits for flags longword. 

j - 

LITERAL 

UIC.FLAG =0, ! /UIC seen 

ENTRIES.FLAG * 1, ! /ENTRIES seen 

PROT.FLAG = 2; ! /PROTECTION seen 

OWN 

!♦ 

! This is the LIB$GET_FOREIGN descriptor block to get the command line. 

i - 

COMMAND.DESC : BLOCK [DSC$K_S_BLN, BYTE], 

COMMAND.BUFF : VECTOR [256, BYTE], 

! + 

! This is the TPARSE argument block. 

i - 


! Mail program 

! No explicit blank processing 
! Validate and assemble UIC 
! Store next directory name 
! Make UIC into directory name 


TPARSE.BLOCK : BLOCK [TPA$K 

INITIAL (TPA$K_C0UNT0, 
TPAIM.ABBREV 
OR TPA$M_BLANKS), 


.LENGTHO, BYTE] 

! Longword count 
! Allow abbreviation 
! Process spaces explicitly 


Keyword flags 
Device string descriptor 
Space to preallocate 
Directory file protection 
Temp for UIC group 
Temp for UIC member 
Actual file owner UIC 
! Number of directory names 
: VECTOR [6. BYTE]. ! Buffer for string 

: BLOCKVECTOR [0, 2], ! Vector of descriptors 


Parser global data: 

PARSER.FLAGS 
DEVICE_STRING 
ENTRY_COUNT, 
FILE.PROTECT. 
UIC.GROUP, 
UIC.MEMBER, 
FILE_OWNER, 
NAME.COUNT. 
UIC.STRING 
NAME.VECTOR 

DIRNAME1 

DIRNAME2 

DIRNAME3 

DIRNAME4 

DIRNAME5 

DIRNAME6 

DIRNAME7 

DIRNAME8 


: BITVECTOR [32]. ! 
: VECTOR [2], ! 

j 

! 

i 

! 

! 


VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2], 

VECTOR 

[2]; 


! Name descriptor 1 
! Name descriptor 2 
! Name descriptor 3 
! Name descriptor 4 
! Name descriptor 5 
! Name descriptor 6 
! Name descriptor 7 
! Name descriptor 8 


• + 

! Structure macro to reference the descriptor fields in the vector of 
! descriptors. 
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; - 


MACRO 




STRING.COUNT 

= 0, 0, 

32. O'/.. 

! Count field 

STRING.ADDR 

= 1. o. 

32, 0%; 

! Address field 

• ♦ 

! TPARSE state table 

to parse the 

command line 



i - 


IINIT.STATE (UFD.STATE, UFD.KEY); 


! Read over the command name (to the first blank in the command). 


ISTATE (START, 

(TPA$_BLANK, . BLANKS.OFF), 

(TPA$_ANY, START) 

); 

!♦ 

! Read device name string and trailing colon. 

j - 

ISTATE (, 

(TPA$_SYMBOL,,,, DEVICE.STRING) 

); 

$STATE (. 

(':’) 

); 


! Read directory string, which is either a UIC string or a general 
! directory string. 

j - 

ISTATE (, 

((UIC),, MAKE.UIC), 

((NAME)) 

); 


! + 

! Scan for options until end of line is reached. 

i - 

ISTATE (OPTIONS, 

('/•). 

(TPAI.EOS, TPAI.EXIT) 

); 

ISTATE (. 

('UIC', PARSE.UIC,, 1“UIC_FLAG, PARSER.FLAGS), 

('ENTRIES', PARSE.ENTRIES,, 1“ENTRIES_FLAG, PARSER.FLAGS), 
('PROTECTION', PARSE.PROT,, 1“PR0T_FLAG, PARSER.FLAGS) 

); 


! Get file owner UIC. 

i - 

ISTATE (PARSE.UIC, 

(':'). 

(...) 

); 

ISTATE (, 

((UIC), OPTIONS) 

); 

• + 

! Get number of directory entries. 

ISTATE (PARSE_ENTRIES, 

(':'). 

(. = .) 

); 

ISTATE (, 

(TPAI.DECIMAL, OPTIONS,,, ENTRY_COUNT) 
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); 


! Get directory file protection. Note that the bit masks generate the 
! protection in complement form. It will be uncomplemented by the main 
! program. 

! - 


ISTATE 

(PARSE.PROT, 

(' = ') 

); 


ISTATE 

(. 

CC) 

); 


ISTATE 

(NEXT.PRO, 

('SYSTEM', SYPR), 
('OWNER', OWPR), 
('GROUP', GRPR), 
('WORLD', WOPR) 

); 


ISTATE 

(SYPR, 

(':'). 

(' = •) 

); 


ISTATE 

(SYPRO, 

OR', SYPRO,, y.X'0001', 
('W. SYPRO,, y.X'0002', 
OE\ SYPRO,, y.X'0004', 
CD'. SYPRO,, XX'0008'. 
(TPA|_LAMBDA, ENDPRO) 

); 

, FILE.PROTECT), 

, FILE.PROTECT), 

, FILE.PROTECT), 

, FILE.PROTECT), 

ISTATE 

(OWPR, 

CO. 

(•=•) 

); 


ISTATE 

(OWPRO, 

CR'. OWPRO,, y.X'0010', 
( ' W' , OWPRO, . y.X' 0020' , 
CE', OWPRO. . y.X'0040', 
CD', OWPRO,, y.X'0080', 
(TPAI.LAMBDA, ENDPRO) 

); 

, FILE.PROTECT), 

, FILE.PROTECT). 

, FILE.PROTECT), 

, FILE.PROTECT), 

ISTATE 

(GRPR, 

C:'). 

(’ = ') 

); 


ISTATE 

(GRPRO, 

('R'. GRPRO. . y.X'0100', 
CW', GRPRO,, y.X'0200\ 
('E', GRPRO. . y.X'0400', 
CD'. GRPRO,, y.X'0800', 
(TPAI.LAMBDA. ENDPRO) 

); 

, FILE.PROTECT), 

, FILE.PROTECT), 

, FILE.PROTECT), 

, FILE.PROTECT), 

ISTATE 

(WOPR. 

(':'). 

CO 

); 


ISTATE 

(WOPRO, 

('R', WOPRO,, y,X'1000' 
CW', WOPRO,, y.X'2000' 
CE', WOPRO,, y.X'4000\ 
CD', WOPRO. . %X' 8000' 
(TPAI.LAMBDA, ENDPRO) 

); 

(ENDPRO, 

, FILE.PROTECT). 

, FILE.PROTECT), 

, FILE.PROTECT), 

, FILE.PROTECT), 

ISTATE 
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(', \ NEXT.PRO), 
O'. OPTIONS) 

); 


Subexpression to parse a UIC string. 


ISTATE 

(UIC. 

('[') 

); 


$STATE 

(. 

(TPAI.OCTAL... 
) ; 

, UIC.GROUP) 

$STATE 

(. 

0 . ') 

); 


$STATE 

(. 

(TPA$_OCTAL,., 

); 

, UIC.MEMBER) 

$STATE 

(, 



(']', TPAI.EXIT, CHECK.UIC) 
); 


! Subexpression to parse a general directory string 


ISTATE 

(NAME. 


('[') 


); 

ISTATE 

(NAMEO, 


(TPAI.STRING,. STORE.NAME) 


); 

ISTATE 

(. 


('.'. NAMEO). 


(•]', TPAI.EXIT) 


); 

PSECT OWN = |OWN|; 

PSECT GLOBAL = $GLOBAL$; 

GLOBAL ROUTINE CREATE.DIR (START.ADDR, CLI.CALLBACK) = 
BEGIN 


! This is the main program of the CREATE/DIRECTORY utility. It gets 
! the command line from the CLI and parses it with TPARSE. 

; - 

LOCAL 

STATUS. 

OUT.LEN : WORD; 

EXTERNAL 

SS$_NORMAL; 

EXTERNAL ROUTINE 

LIB$GET_FOREIGN : ADDRESSING.MODE (GENERAL). 

LIB$TPARSE : ADDRESSING.MODE (GENERAL); 

COMMAND.DESC [DSC$W_LENGTH] = 256; 

COMMAND.DESC [DSC$B_DTYPE] = DSC$K_DTYPE_T; 
COMMAND.DESC [DSC$B_CLASS] = DSC$K_CLASS_S; 
COMMAND.DESC [DSC$A_POINTER] = COMMAND.BUFF; 

STATUS = LIBIGET.FOREIGN (COMMAND.DESC, 

•/.ASCID* COMMAND: \ 

OUT.LEN 

); 

IF NOT .STATUS 
THEN 

SIGNAL (STATUS); 


! Status from LIB$TPARSE 
! length of returned command line 
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Copy the input string descriptor into the TPARSE control block 
and call TPARSE. Note that impure storage is assumed to be zero. 


TPARSE_BLOCK[TPA$L_STRINGCNT] = .OUT.LEN; 

TPARSE_BLOCK[TPA$L_STRINGPTR] = .COMMAND.DESC[DSC$A_POINTER]; 

STATUS = LIB$TPARSE (TPARSE.BLOCK, UFD.STATE, UFD.KEY); 

IF NOT .STATUS 
THEN 

RETURN 0; 

RETURN SS$_N0RMAL 

END; ! End of routine CREATE.DIR 

! + 

! Parser action routines 
! - 
! + 

! Shut off explicit blank processing after passing the command name. 

i - 

ROUTINE BLANKS.OFF = 

BEGIN 

TPARSE.ARGS; 

AP [TPA$V_BLANKS] = 0; 

1 

END; 


! Check the UIC for legal value range. 

i - 

ROUTINE CHECK.UIC = 

BEGIN 

TPARSE.ARGS; 

IF .UIC_GR0UP<16,16> NEQ 0 
OR .UIC_MEMBER<16,16> NEQ 0 
THEN RETURN 0; 

FILE_OWNER<0,16> = .UIC.MEMBER; 
FILE_0WNER<16,16> = .UIC.GROUP; 

1 

END; 


!♦ 

! Store a directory name component. 

i - 

ROUTINE STORE.NAME = 

BEGIN 

TPARSE.ARGS; 

IF .NAME.COUNT GEQU 8 

OR .AP[TPAtL.TOKENCNT] GTRU 9 

THEN RETURN 0; 

NAME.COUNT * .NAME.COUNT + 1; 

NAME.VECTOR [.NAME.COUNT, STRING.COUNT] = .AP[TPA$L_TOKENCNT]; 
NAME.VECTOR [.NAME.COUNT, STRING.ADDR] = .AP[TPA$L_TOKENPTR]; 

1 

END; 


! Convert a UIC into its equivalent directory file name. 

i - 

ROUTINE MAKE.UIC = 

BEGIN 

TPARSE.ARGS; 

IF .UIC_GR0UP<8,8> NEQ 0 
OR .UIC_MEMBER<8,8> NEQ 0 
THEN RETURN 0; 

DIRNAME1[0] = 0; 

DIRNAME1[1] = UIC.STRING; 

$FAOL (CTRSTR = UPLIT (6, UPLIT BYTE (•!OB!OB')), 
OUTBUF = DIRNAME1, 
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PRMLST = UIC.GROUP 
); 
l 

END; 

END 

ELUDOM 


B .TITLE 

.IDENT 


This is a sample program that accepts and parses the command line 
of the CREATE/DIRECTORY command. This program contains the VAX/VMS 
call to acquire the command line from the command interpreter 
and parse it with TPARSE, leaving the necessary information in 
its global data base. The command line has the following format: 

CREATE/DIR DEVICE:[MARANTZ.ACCOUNT.OLD] 

/OWNER_UIC=[2437,25] 

/ENTRIES=100 

/PROTECTION*(SYSTEM:R,OWNER:RWED,GROUP:R,WORLD:R) 

The three qualifiers are optional. Alternatively, the command 
may take the form 

CREATE/DIR DEVICE:[202,31] 
using any of the optional qualifiers. 


! End of module CREATE.DIR 

This BLISS program accepts and parses the command line of a CREATE 
/DIRECTORY command. Note that this code is not from the CREATE 
/DIRECTORY utility. 

CREATE_DIR - Create Directory File 
"X0000" 


; Global data, control blocks, etc. 

f 

f ~ 

.PSECT IMPURE,WRT.NOEXE 

; + 

; Define control block offsets 

f 

ICLIDEF 

ITPADEF 

; + 

; Define parser flag bits for flags longword 

UIC.FLAG = 1 ; /UIC seen 

ENTRIES.FLAG = 2 ; /ENTRIES seen 

PROT.FLAG = 4 ; /PROTECTION seen 


; LIB$GET_FOREIGN string descriptors to get the line to be parsed 

STRING.LEN * 256 
STRING.DESC: 

.WORD STRING.LEN 
.BYTE DSC$K_DTYPE_T 
.BYTE DSCIK.CLASS.S 
.ADDRESS STRING.AREA 
STRING.AREA: 

.BLKB STRING.LEN 
PROMPT.DESC: 

.WORD PROMPT.LEN 
.BYTE DSC$K_DTYPE_T 
.BYTE DSC$K_CLASS_S 
.ADDRESS PROMPT 

PROMPT: 
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PROMPT.LEN = .-PROMPT 


TPARSE argument block 


TPARSE.BLOCK: 
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.LONG 

TPA$K_COUNTO 

i 

; Longword count 


.LONG 

TPA$M_ABBREV! 

j - ; 

; Allow abbreviation 



TPA$M_BLANKS 


; Process spaces explicitly 

• X 

. BLKB 

TPA$K_LENGTH0-8 

; Remainder set at run time 

; Parser global data 





RET.LEN: 


. BLKW 

i 

LENGTH OF RETURNED COMMAND LINE 

PARSER.FLAGS: 

. BLKL 

1 

Keyword flags 

DEVICE.STRING: 

. BLKL 

2 

Device string descriptor 

ENTRY.COUNT: 

.BLKL 

1 

Space to preallocate 

FILE.PROTECT: 

.BLKL 

1 

Directory file protection 

UIC.GROUP: 

.BLKL 

1 

Temp for UIC group 

UIC.MEMBER: 

.BLKL 

1 

Temp for UIC member 

UIC.STRING: 

.BLKB 

6 

String to receive converted UIC 

FILE.OWNER: 

.BLKL 

1 

Actual file owner UIC 

NAME.COUNT: 

.BLKL 

1 

Number of directory names 

DIRNAME1 


.BLKL 

2 

Name 

descriptor 1 

DIRNAME2 


.BLKL 

2 

Name 

descriptor 2 

DIRNAME3 


.BLKL 

2 

Name 

descriptor 3 

DIRNAME4 


.BLKL 

2 

Name 

descriptor 4 

DIRNAME5 


.BLKL 

2 

Name 

descriptor 5 

DIRNAME6 


.BLKL 

2 

Name 

descriptor 6 

DIRNAME7 


.BLKL 

2 

Name 

descriptor 7 

DIRNAME8 


.BLKL 

2 

Name 

descriptor 8 


.SBTTL Main Program 

► 

This is the main program of the CREATE/DIRECTORY utility. It gets 
the command line from the command interpreter and parses it. 


.PSECT 

CODE,EXE,NOWRT 

CREATE.DIR:: 


.WORD 

• -A. 

~M<R2,R3,R4,R5> ; Save registers 

; Call the command interpreter to obtain the command line. 

PUSHAW 

RET.LEN 

PUSHAQ 

PROMPT.DESC 

PUSHAQ 

STRINGJDESC 

CALLS 

#3.G~LIB$GET_F0REIGN ; Call to get command 

BLBC 

RO. SYNTAX.ERR 


Copy the input string descriptor into the TPARSE control block 
-and call LIB$TPARSE. Note that impure storage is assumed to be zero. 

MOVZWL RET.LEN. TPARSE_BLOCK+TPA$L_STRINGCNT 

MOVAL STRING.AREA. TPARSE_BLOCK+TPA$L_STRINGPTR 

PUSHAL UFD.KEY 

PUSHAL UFD.STATE 

PUSHAL TPARSE.BLOCK 

CALLS #3,G~LIB$TPARSE 

BLBC RO,SYNTAX.ERR 



Parsing is complete. 

You can include here code to process the string just parsed, to call 
another program to process the command, or to return control to 
a calling program, if any. 

SYNTAX_ERR: 
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Code to handle parsing errors. 

RET 

.SBTTL Parser State Table 


Assign values for protection flags to be used when parsing protection 
string. 


SYSTEM.READ.FLAG = ~X0001 
SYSTEM_WRITE_FLAG = ~X0002 
SYSTEM_EXECUTE_FLAG = ~X0004 
SYSTEM.DELETE.FLAG = “X0008 
GROUP_READ_FLAG * ~X0001 
GROUP.WRITE.FLAG = ‘X0002 
GROUP.EXECUTE.FLAG = “X0004 
GROUP_DELETE_FLAG = ~X0008 
OWNER.READ.FLAG = ~X0001 
OWNER.WRITE.FLAG = ~X0002 
OWNER.EXECUTE.FLAG * ~X0004 
OWNER.DELETE.FLAG * ~X0008 
WORLD_READ_FLAG = ~X0001 
WORLD_WRITE_FLAG * “X0002 
WORLD_EXECUTE_FLAG = “X0004 
WORLD.DELETE.FLAG = ~X0008 


$INIT_STATE UFD.STATE,UFD.KEY 


+ 

Read over the command name (to the first blank in the command). 


$STATE START 

$TRAN TPA$_BLANK,,BLANKS.OFF 

$TRAN TPA$_ANY.START 


♦ 

Read device name string and trailing colon. 


$STATE 

$TRAN TPA$_SYMBOL,,,,DEVICE.STRING 


ISTATE 

$TRAN ':' 

Read directory string, which is either a UIC string or a general 
directory string. 

$STATE 

$TRAN !UIC,.MAKE.UIC 

$TRAN !NAME 


+ 

Scan for options until end of line is reached 


ISTATE 

ITRAN 

ITRAN 

ISTATE 

ITRAN 

ITRAN 

ITRAN 


OPTIONS 

TPAI.EOS,TPAI.EXIT 

'OWNER.UIC',PARSE_UIC,.UIC.FLAG,PARSER.FLAGS 
•ENTRIES'.PARSE.ENTRIES,,ENTRIES.FLAG,PARSER.FLAGS 
•PROTECTION',PARSE.PROT,,PROT.FLAG,PARSER.FLAGS 


Get file owner UIC. 

ISTATE PARSE.UIC 

ITRAN ':' 

ITRAN 

ISTATE 

ITRAN !UIC,OPTIONS 
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+ 

Get number of directory entries 


ISTATE 

$TRAN 

$TRAN 

PARSE.ENTRIES 

i . i 

1 s ' 

$STATE 

$TRAN 

TPA$_DECIMAL,OPTIONS,,.ENTRY.COUNT 


Get directory file protection. Note that the bit masks generate the 
protection in complement form. It will be uncomplemented by the main 
program. 


ISTATE 

$TRAN 

$TRAN 

PARSE.PROT 

i . i 

1 = • 

$STATE 

$TRAN 

'(• 

ISTATE 

$TRAN 

$TRAN 

$TRAN 

$TRAN 

NEXT.PRO 
'SYSTEM', SYPR 
'OWNER', OWPR 
'GROUP', GRPR 
'WORLD', WOPR 

ISTATE 

ITRAN 

ITRAN 

SYPR 

1 . 1 

1 — 1 

ISTATE 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

SYPRO 

'R',SYPRO,,SYSTEM_READ_FLAG.FILE.PROTECT 
•W'.SYPRO,,SYSTEM_WRITE_FLAG,FILE.PROTECT 
'E',SYPRO..SYSTEM.EXECUTE.FLAG,FILE.PROTECT 
'D'.SYPRO,,SYSTEM_DELETE_FLAG,FILE.PROTECT 
TPAI.LAMBDA,ENDPRO 

ISTATE 

ITRAN 

ITRAN 

OWPR 

• . i 

•s' 

ISTATE 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

OWPRO 

'R'.OWPRO,,OWNER_READ_FLAG,FILE.PROTECT 
•W'.OWPRO..OWNER.WRITE.FLAG,FILE.PROTECT 
•E'.OWPRO,.OWNER.EXECUTE.FLAG,FILE.PROTECT 
'D',OWPRO,,OWNER.DELETE.FLAG,FILE.PROTECT 
TPAI.LAMBDA.ENDPRO 

iSfATE 

ITRAN 

ITRAN 

GRPR 

i . i 

• s • 

ISTATE 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

GRPRO 

•R'.GRPRO,,GROUP.READ.FLAG,FILE.PROTECT 
•W'.GRPRO,.GROUP.WRITE.FLAG,FILE.PROTECT 
'E'.GRPRO,,GROUP.EXECUTE.FLAG,FILE.PROTECT 
•D'.GRPRO,.GROUP.DELETE.FLAG,FILE.PROTECT 
TPAI.LAMBDA,ENDPRO 

ISTATE 

ITRAN 

ITRAN 

WOPR 

i . i 

• s 1 

ISTATE 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

ITRAN 

WOPRO 

'R'.WOPRO,.WORLD.READ.FLAG,FILE.PROTECT 
'W'.WOPRO,.WORLD.WRITE.FLAG,FILE.PROTECT 
'E'.WOPRO,.WORLD.EXECUTE.FLAG,FILE.PROTECT 
•D'.WOPRO,.WORLD.DELETE.FLAG,FILE.PROTECT 
TPAI.LAMBDA,ENDPRO 

ISTATE 

ITRAN 

ITRAN 

ENDPRO 

NEXT.PRO 
')'.OPTIONS 
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Subexpression to parse a UIC string. 


$STATE 

UIC 


$TRAN 

' f 


$STATE 

ITRAN 

TPAI.OCTAL,. 

,.UIC.GROUP 

ISTATE 

ITRAN 

<• , •> 

; The comma character must be 


; surrounded by angle brackets 

; because MACRO restricts the use 

; of commas in arguments to macros. 

ISTATE 

ITRAN TPA$_0CTAL,,,,UIC.MEMBER 

$STATE 

$TRAN ']•,TPAl.EXIT,CHECK.UIC 


♦ 

Subexpression to parse a general directory string 


ISTATE 

NAME 


ITRAN 

'[* 


ISTATE 

NAMEO 


ITRAN 

TPAI.STRING,.STORE.NAME 


ISTATE 

ITRAN 

'.',NAMEO 


ITRAN 

']'.TPAI.EXIT 


lEND.STATE 

.SBTTL 

Parser Action Routines 


.PSECT 

CODE,EXE,NOWRT 


; + 

; Shut off explicit blank processing after passing the command name. 

BLANKS.OFF: 

.WORD 

0 ; 

No registers saved (or used) 

BBCC 

#TPA|V_BLANKS.TPAlL.OPTIONS(AP),10| 

101: RET 

; + 

; Check the UIC for 

legal value range. 


CHECK.UIC: 

.WORD 

0 ; 

No registers saved (or used) 

TSTW 

UIC.GROUP-► 2 ; 

UIC components are 16 bits 

BNEQ 

101 


TSTW 

UIC.MEMBER+2 


BNEQ 

101 


MOVW 

UIC.GROUP.FILE.OWNER+2 ; 

Store actual UIC 

MOVW 

UIC.MEMBER.FILE.OWNER ; 

after checking 

RET 

101: CLRL 

RO ; 

Value out of range - fail 

RET 

: 

the transition 

; ♦ 

; Store a directory 

name component. 


STORE.NAME: 

.WORD 

0 ; 

No registers saved (or used) 

MOVL 

NAME.COUNT,R1 ; 

Get count of names so far 

CMPL 

Rl,#8 ; 

Maximum of 8 permitted 

BGEQU 

101 


INCL 

NAME.COUNT ; 

Count this name 

MOVAQ 

DIRNAME1[Rl],R1 ; 

Address of next descriptor 

MOVQ 

TPAIL.TOKENCNT(AP),(Rl) ; 

Store the descriptor 

CMPL 

(Rl),#9 ; 

Check the length of the name 

BGTRU 

101 ; 

Maximum is 9 

RET 
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10$: CLRL R0 

RET 


; Error in directory name 


Convert a UIC into its equivalent directory file name. 


MAKE.UIC: 

.WORD 

TSTB 

BNEQ 

TSTB 

BNEQ 

MOVL 

MOVAL 

$FA0L 


RET 

10$: CLRL 

RET 

FAO.STRING: 

STRING.START: 

STRING.END: 


0 

UIC.GROUP+l 

10 $ 

UIC_MEMBER+1 

10 $ 

#6,DIRNAME1 
UIC.STRING,DIRNAME1+4 
CTRSTR=FA0_STRING,- 
0UTBUF=DIRNAME1,- 
PRMLST=UIC_GROUP 


; No registers saved (or used) 
; Check UIC for byte values, 

; Since UIC type directories 
; Are restricted to this form 

; Directory name is 6 bytes 
; Point to string buffer 
; Convert UIC to octal string 


RO 


Range error - fail it 


.LONG STRING_END-STRING_START 

.ASCII 1 !OB!OB' 


.END CREATE.DIR 


This MACRO program accepts and parses the command line of a CREATE 
/DIRECTORY command. Note that this code is not from the CREATE 
/DIRECTORY utility. 
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LIB$TRA_ASC—EBC—Translate ASCII to 

EBCDIC 



LIB$TRA_ASC_EBC translates an ASCII string to an EBCDIC string. 

FORMAT 

LI B$TRA_ASC_EBC src-str ,dst-str 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

src-str 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

Source string (ASCII) to be translated by LIB$TRA_ASC—EBC . The src-str 

argument contains the address of a descriptor pointing to this source string. 

dst-str 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: write only 

mechanism: by descriptor 

Destination string (EBCDIC). The dst-str argument contains the address of a 
descriptor pointing to this destination string. 

DESCRIPTION 

LIB$TRA_ASC—EBC translates an ASCII string to an EBCDIC string. If the 

destination string is a fixed-length string, its length must match the length of 
the input string. No filling is done. 

A similar operation can be accomplished by specifying the ASCII-to-EBCDIC 
translation table LIB$AB_ASC_EBC in a routine using LIB$MOVTC, but no 
testing for untranslatable characters is done under those circumstances. 

This routine uses the ASCII-to-EBCDIC translation table RTL-18 shown 
below. 

ASCII to EBCDIC Translation Table 

• The number on the left represents the low-order bits of the ASCII 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the ASCII 
character in hexadecimal notation. 
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• The number in the body of the table represents the equivalent EBCDIC 
character in hexadecimal notation. 


Table RTL-18 LIB$AB_ASC_EBC 


Row 

bits 0-3 




Column 



bits 4 - 

7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

40 

FO 

7C 

D7 

79 

97 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

1 

01 

11 

4F 

FI 

Cl 

D8 

81 

98 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

2 

02 

12 

7F 

F2 

C2 

D9 

82 

99 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3 

03 

13 

7B 

F3 

C3 

E2 

83 

A2 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

4 

37 

3C 

5B 

F4 

C4 

E3 

84 

A3 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

5 

2D 

3D 

6C 

F5 

C5 

E4 

85 

A4 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

6 

2E 

32 

50 

F6 

C6 

E5 

86 

A5 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

7 

2F 

26 

7D 

F7 

C7 

E6 

87 

A6 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

8 

16 

18 

4D 

F8 

C8 

E7 

88 

A7 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

9 

05 

19 

5D 

F9 

C9 

E8 

89 

A8 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

A 

25 

3F 

5C 

7A 

D1 

E9 

91 

A9 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

B 

OB 

27 

4E 

5E 

D2 

4A 

92 

CO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

C 

OC 

1C 

6B 

4C 

D3 

EO 

93 

6A 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

D 

OD 

ID 

60 

7E 

D4 

5A 

94 

DO 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

E 

OE 

IE 

4B 

6E 

D5 

5F 

95 

A1 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

F 

OF 

IF 

61 

6F 

D6 

6D 

96 

07 

3F 

3F 

3F 

3F 

3F 

3F 

3F 

FF 
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CONDITION SS$_NORMAL 
VALUES LIB$_INVCHA 

RETURNED 

LIB$_INVARG 


Routine successfully completed. 

One or more occurrences of an untranslatable 
character have been detected during the translation. 

If the destination string is a fixed-length string 
and its length is not the same as the source string 
length, no translation is attempted. 


EXAMPLE 


IDENTIFICATION DIVISION. 
PROGRAM-ID. TRANS. 


ENVIRONMENT DIVISION. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 INPUT-STRING PIC X(4). 

01 EBCDIC-STRING PIC X(4). 

01 OUT-STRING PIC X(4). 

01 FILL-CHAR PIC X VALUE "<9" . 

01 SS-STATUS PIC S9(9) COMP. 

88 SS-NORMAL VALUE 01. 


01 EBCDIC-TABLE. 

05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 
05 FILLER PIC X(16) VALUE 


•• (9 <9(9 (9 <9 (9 <9 <9 <9 <9 <9 <9 <9 <9 <9 <9 " 

•• Q (9 (9 <3(9 (9 (9 <9 <9(9 (9 <9 <9 <9 (9 (9 " 

11 (Q (Q (Q (9 < 9(9 (9 (9 <9 (9 <9 <9 < 9(9 (9 (Q " 
n (9(9(9Q®® <9<9<9<9<D<9Q<9<S<9 " . 

" qqqqqqqqq®.<(+|". 
"&QQQQ®®®®®! $*) ; <8" . 
"-/<S<Q<9<9<S<9<Q<S<9,7,_>?" . 
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05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 
05 FILLER PIC X(16) 


VALUE " ©©©©©©©©a© :#©'="" " 
VALUE "©abcdefghi©©©©®®" . 
VALUE "«jklmnopqr©©©©©«". 
VALUE "©©stuvwxyz©®©©©©". 
VALUE "©a©©©©©©©©©©©©©©". 
VALUE "©ABCDEFGHI©©©©©©". 
VALUE "!JKLMNOPQR©©©©©®". 
VALUE "©©STUVWXYZ©©©©©®". 
VALUE "0123456789©©©©©©". 


PROCEDURE DIVISION. 


001-MAIN. 

DISPLAY " ". 

DISPLAY "ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: " 
WITH NO ADVANCING. 

ACCEPT INPUT-STRING 
AT END STOP RUN. 

IF INPUT-STRING = "EXIT" OR "exit" OR " 

STOP RUN. 


CALL "LIB$TRA_ASC_EBC" 

USING BY DESCRIPTOR INPUT-STRING, EBCDIC-STRING 
GIVING SS-STATUS. 

IF SS-NORMAL 

CALL "LIBSMOVTC" 

USING BY DESCRIPTOR EBCDIC-STRING, 

FILL-CHAR, 

EBCDIC-TABLE, 

OUT-STRING, 

GIVING SS-STATUS 
IF SS-NORMAL 

DISPLAY "ASCII ENTERED WAS: " INPUT-STRING 
DISPLAY "EBCDIC TRANSLATED IS: " OUT-STRING 
ELSE 

DISPLAY "*** LIBIMOVTC TRANSLATION UNSUCCESSFUL ***" 

ELSE 

DISPLAY "*** LIB$TRA_ASC_EBC TRANSLATION UNSUCCESSFUL ***". 
GO TO 001-MAIN. 


This COBOL program uses LIB$TRA_ASC—EBC to translate an ASCII string 

to EBCDIC. If successful, it then uses LIB$MOVTC to translate the EBCDIC 
string back to ASCII. 

To exit from this program, you must type CTRL/Z. The output generated by 
this COBOL program is as follows: 

$ RUN TRANS 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: abdc 
ASCII ENTERED WAS: abdc 
EBCDIC TRANSLATED IS: abdc 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: ~=b& 

ASCII ENTERED WAS: ~=b& 

EBCDIC TRANSLATED IS: ®=b& 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: 8“'/.$ 

ASCII ENTERED WAS: 8^*/.$ 

EBCDIC TRANSLATED IS: 8©'/.$ 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: /x 
ASCII ENTERED WAS: /x 
EBCDIC TRANSLATED IS: /xfi! 

ENTER 4 CHARACTERS TO BE TRANSLATED ASCII TO EBCDIC: CTRL/Z 
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LIB$TRA_EBC_ASC—Translate EBCDIC to 

ASCII 



LIB$TRA_EBC_ASC translates an EBCDIC string to an ASCII string. 

FORMAT 

LIB$TRA_EBC_ASC src-str ,dst-str 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: read only 

mechanism: by value 

ARGUMENTS 

src-str 

VMS Usage: byte_unsigned 
type: byte (unsigned) 

access: read only 

mechanism: by descriptor 

String (EBCDIC) to be translated by LIB$TRA_EBC_ASC. The src-str 

argument contains the address of a descriptor pointing to this source string. 

dst-str 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Destination string (ASCII). The dst-str argument contains the address of the 
descriptor of this destination string. 

This routine uses the EBCDIC-to-ASCII translation table at LIB$AB_EBC_ 
ASC. 

DESCRIPTION 

LIB$TRA_EBC—ASC translates an EBCDIC string to an ASCII string. If the 
destination string is a fixed-length string, its length must match the length of 
the input string. No filling is done. 

A similar operation can be accomplished by specifying the EBCDIC-to-ASCII 
translation table LIB$AB_EBC_ASC in a routine using LIB$MOVTC, but no 
testing for untranslatable characters is done under these circumstances. 

This routine uses the EBCDIC-to-ASCII translation table RTL-19 shown 
below. 

EBCDIC to ASCII Translation Table 

• The number on the left represents the low-order bits of the EBCDIC 
character in hexadecimal notation. 

• The number across the top represents the high-order bits of the EBCDIC 
character in hexadecimal notation. 
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CONDITION 

VALUES 

RETURNED 


• The number in the body of the table represents the equivalent ASCII 
character in hexadecimal notation. 

Table RTL-19 LIB$AB_EBC_ASC 


Row 

bits 0-3 




Column 



bits 4 - 

- 7 






0 

1 

2 

3 

4 

5 

6 

7 

8 

9 

A 

B 

C 

D 

E 

F 

0 

00 

10 

5C 

5C 

20 

26 

2D 

5C 

5C 

5C 

5C 

5C 

7 B 

7D 

5C 

30 

1 

01 

11 

5C 

5C 

5C 

5C 

2F 

5C 

61 

6A 

7E 

5C 

41 

4A 

5C 

31 

2 

02 

12 

5C 

16 

5C 

5C 

5C 

5C 

62 

6B 

73 

5C 

42 

4B 

53 

32 

3 

03 

13 

5C 

5C 

5C 

5C 

5C 

5C 

63 

6C 

74 

5C 

43 

4C 

54 

33 

4 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

64 

6D 

75 

5C 

44 

4D 

55 

34 

5 

09 

5C 

0A 

5C 

5C 

5C 

5C 

5C 

65 

6E 

76 

5C 

45 

4E 

56 

35 

6 

5C 

08 

17 

5C 

5C 

5C 

5C 

5C 

66 

6F 

77 

5C 

46 

4F 

57 

36 

7 

7F 

5C 

IB 

04 

5C 

5C 

5C 

5C 

67 

70 

78 

5C 

47 

50 

58 

37 

8 

5C 

18 

5C 

5C 

5C 

5C 

5C 

5C 

68 

71 

79 

5C 

48 

51 

59 

38 

9 

5C 

19 

5C 

5C 

5C 

5C 

5C 

60 

69 

72 

7A 

5C 

49 

52 

5A 

39 

A 

5C 

5C 

5C 

5C 

5B 

5D 

7C 

3A 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

B 

0B 

5C 

5C 

5C 

2E 

24 

2C 

23 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

C 

OC 

1C 

5C 

14 

3C 

2A 

25 

40 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

D 

0D 

ID 

05 

15 

28 

29 

5F 

27 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

E 

0E 

IE 

06 

5C 

2B 

3B 

3E 

3D 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

F 

OF 

IF 

07 

1A 

21 

5E 

3F 

22 

5C 

5C 

5C 

5C 

5C 

5C 

5C 

FF 
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SS$_NORMAL 

LIB$_INVCHA 

LIB$_INVARG 


Routine successfully completed. 

One or more occurrences of an untranslatable 
character have been detected during the translation. 

If the destination string is a fixed-length string 
and its length is not the same as the source string 
length, no translation is attempted. 
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LIB$TRAVERSE—TREE—Traverse a 

Balanced Binary 
Tree 



LIB$TRAVERSE_TREE calls an action routine for each node in a 
binary tree. 

FORMAT 

LIB$TRAVERSE_TREE treehead,action-rtn 

[,user-data] 

RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENTS 

treehead 

VMS Usage: longword—unsigned 
type: longword (unsigned) 

access: read only 

mechanism: by reference 

Tree head of the binary tree. The treehead argument is the address of an 
unsigned longword that is the tree head in the binary tree traversal. 

action-rtn 

VMS Usage: procedure 
type: procedure entry mask 

access: function call (before return) 

mechanism: by reference, procedure reference 

User-supplied action routine called by LIB$TRAVERSE_TREE for each node 
in the tree. The action-rtn argument is the address of the entry mask to the 
action routine. 

For more information, see "Call Format for an Action Routine" in the 
Description section. 

user-data 

VMS Usage: user—arg 
type: unspecified 

access: read only 

mechanism: by reference 

User data that LIB$TRAVERSE—TREE passes to your action routine. The 
user-data argument contains the address of this user data. This is an optional 
argument; the default value is zero. 
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DESCRIPTION LIB$TRAVERSE_TREE calls a user-supplied action routine for each node to 

traverse a balanced binary tree. 

Call Format for an Action Routine 

The format of the call is as follows: 

action-rtn treehead .user-data 

LIB$TRAVERSE_TREE passes the treehead and user-data arguments to your 
action routine by reference. 

This action routine is defined by you to fit your own purposes. A common 
use of an action routine here is to print the contents of each node during the 
tree traversal. 

This is one example of a user-supplied action routine. 

1 ’/.TITLE 1 LIB$ Tree Example in BASIC V2' 

'/.SBTTL 'Function to display a node' 

FUNCTION LONG PRINT.NODE (NODE.TYPE NODE. LONG DUMMY) 

! + 

! Print the string contained in the current node 

i - 

OPTION TYPE = EXPLICIT 
RECORD NODE.TYPE 

BYTE HEADER (9) ! Header 

BYTE LENGTH ! Length 

STRING TEXT = 80 ! String 

END RECORD NODE.TYPE 

PRINT SEG$ (NODE::TEXT. 1%. NODE::LENGTH) 

PRINT.NODE * I*/. 

END FUNCTION 


CONDITION 

VALUES 

RETURNED 


LIB$_NORMAL Success. Traversal complete. 

Any condition value returned by your action routine. 


EXAMPLE 


The BASIC example provided in the description of LIB$INSERT_TREE also 
demonstrates the use of LIB$TRAVERSE_TREE. Please refer to that example 
for assistance in using this procedure. 
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LIB$TRIM_FILESPEC—Fit Long File 

Specification into 
Fixed Field 

LIB$TRIM_FILESPEC takes a file specification, such as an RMS 
resultant name string, and shortens it (if necessary) so that it fits 
into a field of fixed width. 


• 

FORMAT 

LIB$TRIM_FILESPEC in-file ,out-file [, width] 

[, out-len] 


RETURNS 

VMS Usage: cond—value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

• 

ARGUMENTS 

in-file 

VMS Usage: char_string 
type: character string 

access: read only 

mechanism: by descriptor 

File specification to be trimmed. The in-file argument contains the address of 
a descriptor pointing to this file specification string. 

The file specification should be an RMS resultant name string. The error 
LIB$_INVARG is returned if in-file contains more than 255 characters. 

• 


out-file 

VMS Usage: char_string 
type: character string 

access: write only 

mechanism: by descriptor 

Trimmed file specification. The out-file argument contains the address of 
a descriptor pointing to this trimmed file specification string. LIB$TRIM_ 
FILESPEC writes the trimmed file specification into out-file. 

• 


width 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: read only 

mechanism: by reference 

Maximum field width desired. The width argument is the address of an 
unsigned word that contains this maximum field width. 

If omitted, the current length of out-file is used. If out-file is not a fixed- 
length string, you should specify width to ensure that the desired width is 
used. 
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out-len 

VMS Usage: word-unsigned 
type: word (unsigned) 

access: write only 

mechanism: by reference 

Length of the trimmed file specification, not including any blank padding or 
truncated characters. The out-len argument is the address of an unsigned 
word that contains this length. This is an optional argument. 


DESCRIPTION This routine trims file specifications in a consistent, predictable manner to fit 

in a fixed-length field using the same algorithm that DIGITAL software uses. 

LIB$TRIM__FILESPEC allows compilers and other utilities which need to 
display file specifications in fixed-length fields, such as listing headers, to 
display file specifications in a consistent fashion. 

If necessary to make the file specification fit into the specified field width, 
LIB$TRIM__FILESPEC removes portions of the file specification in this order. 

1 Node (including access control) 

2 Device 

3 Directory 

4 Version 

5 Type 

If, after removing all these fields, the file name is still longer than the field 
width, the file name is truncated and the alternate success status LIB$_ 
STRTRU is returned. 

LIB$TRIM__FILESPEC supports any string class for the in-file and out-file 
string arguments. 


CONDITION 

VALUES 

RETURNED 


SSS—NORMAL 

LIB$_STRTRU 

LIB$_INVARG 

LIB$_INVSTRDES 

LIB$_WRONUMARG 


Routine successfully completed. 

Success, but the output string was truncated. 
Significant characters of the trimmed file 
specification were truncated. 

Invalid argument. In-file contained more than 255 
characters. 

Invalid string descriptor. 

Wrong number of arguments. 


Any condition values returned by LIB$SCOPY_R_DX. 

Any condition values returned by the $FILESCAN system service. 
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EXAMPLE 

PROGRAM TRIM_FILESPEC(INPUT,OUTPUT); 

{+> 

{ This PASCAL example program demonstrates the 
{ use of LIB$TRIM_FILESPEC. 

{-> 


TYPE 

WORD = [WORD] 0..65535; 

VAR 

INPUT_FILESPEC : VARYING [255] OF CHAR; 
OUTPUT.FILESPEC : VARYING [32] OF CHAR; 
RETURNED.STATUS : INTEGER; 

[EXTERNAL] FUNCTION LIB$TRIM_FILESPEC( 

IN.FILE : VARYING [LENi] OF CHAR; 

VAR OUT.FILE : VARYING [LEN2] OF CHAR; 

WIDTH : WORD := 7.IMMED 0; 

OUT.LEN : [REFERENCE] WORD := 7.IMMED 0 

) : INTEGER; EXTERNAL; 

[EXTERNAL] FUNCTION LIB$STOP( 

CONDITION.STATUS : [IMMEDIATE,UNSAFE] UNSIGNED; 
FAO.ARGS : [IMMEDIATE,UNSAFE,LIST] UNSIGNED 

) : INTEGER; EXTERNAL; 


BEGIN 

{♦> 

< Start with a large INPUT.FILESPEC. 

{-> 

INPUT.FILESPEC := 'DISK$NAME:[DIRECTORY1.DIRECT0RY2]FILENAME.EXTENSTION;1•; 

{ Use LIB$TRIM_FILESPEC to shorten it to fit a smaller variable. 

{-> 

RETURNED_STATUS := LIB$TRIM_FILESPEC( 

INPUT.FILESPEC, 

OUTPUT.FILESPEC, 

SIZE(OUTPUT.FILESPEC.BODY)); 

IF NOT ODD(RETURNED.STATUS) 

THEN 

LIB$STOP(RETURNED.STATUS); 

<+> 

i Print out the original filename along with the 
{ shortened filename . 

<-> 

WRITELN('Original filespec ',INPUT.FILESPEC); 

WRITELNC'Shortened filespec '.OUTPUT.FILESPEC); 

END. 


This PASCAL example program demonstrates the use of LIB$TRIM_ 
FILESPEC. The output generated by this program is as follows: 

Original filespec DISK$NAME:[DIRECTORY1.DIRECT0RY2]FILENAME.EXTENSTION;1 
Shortened filespec FILENAME.EXTENSTION;1 
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LIB$WAIT 


LIB$WAIT—Wait a Specified Period of 



Time 

LIB$WAIT places the current process into hibernation for the 
number of seconds specified in its argument. 

FORMAT 

LIBS WAIT seconds 

RETURNS 

VMS Usage: cond_value 
type: longword (unsigned) 

access: write only 

mechanism: by value 

ARGUMENT 

seconds 

VMS Usage: floating-point 
type: F_floating 

access: read only 

mechanism: by reference 

The number of seconds to wait. The seconds argument contains the address 
of an F_floating number that is this number. 

The value is rounded to the nearest hundredth-second before use. Seconds 
must be between 0.0 and 100,000.0. 

DESCRIPTION 

LIB$WAIT rounds the value specified by seconds to the nearest hundredth- 
second, uses the $SCHDWK system service to schedule a wakeup for that 
interval, and then issues the $HIBER system service to hibernate until the 
wakeup occurs. 

Due to other system activity, the length of time that the process actually waits 
may be somewhat longer than what was specified by seconds. 

The process hibernates in the caller's access mode; therefore, asynchronous 
system traps (ASTs) may be delivered while the process is hibernating. See 
the VAX/VMS System Services Reference Manual for more information. 

CONDITION 

VALUES 

RETURNED 

SSS—NORMAL Routine successfully completed. 

LIB$_INVARG Invalid argument. The value of seconds was less 

than zero or was greater than 100,000.0 

LIB$_WRONUMARG Wrong number of arguments. An incorrect number 

of arguments was passed to LIBSWAIT. 

Any condition values returned by the $SCHDWK system service. 
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EXAMPLE 


IDENTIFICATION DIVISION. 
PROGRAM-ID. SAMPLE. 

DATA DIVISION. 

WORKING-STORAGE SECTION. 

01 DELAY COMP-1. 

PROCEDURE DIVISION. 
START-SAMPLE. 

MOVE 3.5 TO DELAY. 

CALL "LIBIWAIT" 

USING BY REFERENCE DELAY. 
STOP RUN. 


This COBOL program demonstrates the use of LIB$WAIT. When run, it waits 
for 3.5 seconds and then exits. 
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